{"id":45905821,"url":"https://github.com/mk3008/rawsql-ts","last_synced_at":"2026-06-10T01:01:01.462Z","repository":{"id":282239477,"uuid":"946650796","full_name":"mk3008/rawsql-ts","owner":"mk3008","description":"SQL-first lifecycle toolkit for testing, inspecting, and evolving database applications.","archived":false,"fork":false,"pushed_at":"2026-06-08T13:23:56.000Z","size":16173,"stargazers_count":29,"open_issues_count":16,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-08T14:25:18.468Z","etag":null,"topics":["ast","code-generation","database-tooling","raw-sql","schema-evolution","sql","sql-first","sql-parser","testing","typescript"],"latest_commit_sha":null,"homepage":"https://mk3008.github.io/rawsql-ts/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mk3008.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["mk3008"]}},"created_at":"2025-03-11T13:20:24.000Z","updated_at":"2026-06-08T13:22:30.000Z","dependencies_parsed_at":"2025-04-15T12:44:42.990Z","dependency_job_id":"a1c23911-229c-490c-bc94-1d02b99fa3af","html_url":"https://github.com/mk3008/rawsql-ts","commit_stats":null,"previous_names":["mk3008/ts-sample","mk3008/carbunqlex-ts","mk3008/rawsql-ts"],"tags_count":151,"template":false,"template_full_name":null,"purl":"pkg:github/mk3008/rawsql-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk3008%2Frawsql-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk3008%2Frawsql-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk3008%2Frawsql-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk3008%2Frawsql-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mk3008","download_url":"https://codeload.github.com/mk3008/rawsql-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk3008%2Frawsql-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34132030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"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":["ast","code-generation","database-tooling","raw-sql","schema-evolution","sql","sql-first","sql-parser","testing","typescript"],"created_at":"2026-02-28T02:43:34.645Z","updated_at":"2026-06-10T01:01:01.449Z","avatar_url":"https://github.com/mk3008.png","language":"TypeScript","funding_links":["https://github.com/sponsors/mk3008"],"categories":[],"sub_categories":[],"readme":"# rawsql-ts\n\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n\nA monorepo for **rawsql-ts**: a SQL-first toolkit for parsing, testing, inspecting, and evolving database applications while keeping raw SQL as a first-class asset.\n\nBy parsing SQL into abstract syntax trees, rawsql-ts enables type-safe query building, static validation, fixture-backed testing, and transparent result mapping while preserving the expressiveness and control of handwritten SQL. AST-based rewriting also powers Zero Table Dependency (ZTD) testkits, which transform application queries to run against in-memory fixtures instead of physical tables.\n\nThe former `@rawsql-ts/ztd-cli` package has moved to the Ashiba project as `@ashiba-ts/cli`. Use [mk3008/ashiba](https://github.com/mk3008/ashiba) for SQL-first scaffolding, command-line inspection, optional-condition maintenance, and project lifecycle workflows.\n\n\u003e [!Note]\n\u003e This project is currently in beta. APIs may change until the v1.0 release.\n\n## Capability Index\n\nUse this section as the shortest repo-level map. It is intentionally brief: package details live under each package README, while repo-level workflows point to the CLI or guide that owns them.\n\n### Packaged Capabilities\n\n| Capability | Primary surface | Start here |\n|------------|-----------------|------------|\n| SQL parsing and AST rewriting | `rawsql-ts` | [packages/core](./packages/core) |\n| SQL impact analysis / grep | `@rawsql-ts/sql-grep-core` | [packages/sql-grep-core](./packages/sql-grep-core) |\n| Execution helpers | `@rawsql-ts/executor` | [packages/executor](./packages/executor) |\n| Production SQL driver adapter primitives | `@rawsql-ts/driver-adapter-core` | [packages/drivers/driver-adapter-core](./packages/drivers/driver-adapter-core) |\n| ZTD fixture rewriting and testkits | `@rawsql-ts/testkit-*` | [packages/testkit-core](./packages/testkit-core) |\n| Test evidence storage and rendering | `@rawsql-ts/test-evidence-*` | [packages/test-evidence-core](./packages/test-evidence-core) |\n| Schema documentation generation | `@rawsql-ts/ddl-docs-*` | [packages/ddl-docs-cli](./packages/ddl-docs-cli) |\n| Ashiba CLI workflows | `@ashiba-ts/cli` | [mk3008/ashiba](https://github.com/mk3008/ashiba) |\n\n### Workflow Surfaces\n\nThese workflows are now owned by Ashiba. rawsql-ts keeps the reusable parser, formatter, testkit, binder, SQL grep, and documentation packages that Ashiba can consume.\n\n| Workflow | Entry point | Why it matters |\n|----------|-------------|----------------|\n| SQL impact analysis before schema changes | `@rawsql-ts/sql-grep-core` / Ashiba query commands | Supports rename/type-change investigations using AST-based usage analysis. |\n| SQL-first optional filter authoring | `rawsql-ts` SSSQL APIs / Ashiba query commands | Keeps optional filters visible in SQL while runtime pruning stays explicit. Runtime no longer injects new filter predicates. |\n| Fixture-backed SQL unit testing | `@rawsql-ts/testkit-*` | Runs SQL against deterministic fixtures without a production database dependency. |\n| Schema documentation generation | `@rawsql-ts/ddl-docs-*` | Generates reviewable Markdown schema documentation from DDL assets. |\n\n## Packages\n\n### Core\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [rawsql-ts](./packages/core) | ![npm](https://img.shields.io/npm/v/rawsql-ts) | SQL parser and AST transformer. Zero dependencies, browser-ready. |\n| [@rawsql-ts/sql-grep-core](./packages/sql-grep-core) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/sql-grep-core) | Low-dependency SQL usage analysis engine for AST-based schema impact checks. |\n\n### Production Driver Adapters\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [@rawsql-ts/driver-adapter-core](./packages/drivers/driver-adapter-core) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/driver-adapter-core) | Driver-neutral SQL client contract and named-parameter compilation helpers. |\n\n### Execution\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [@rawsql-ts/executor](./packages/executor) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/executor) | Optional helper for connection lifecycle and transaction scope when you want less boilerplate while keeping execution ownership in the caller. |\n\n### Testing\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [@rawsql-ts/testkit-core](./packages/testkit-core) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/testkit-core) | Fixture-backed CTE rewriting and schema validation engine. Driver-agnostic ZTD foundation. |\n| [@rawsql-ts/testkit-postgres](./packages/testkit-postgres) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/testkit-postgres) | Postgres-specific CTE rewriting and fixture validation. Works with any executor. |\n| [@rawsql-ts/adapter-node-pg](./packages/adapters/adapter-node-pg) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/adapter-node-pg) | Testkit adapter connecting `pg` (node-postgres) to `@rawsql-ts/testkit-postgres`; retained under its legacy name until a non-breaking `testkit-adapter-*` alias exists. |\n| [@rawsql-ts/testkit-sqlite](./packages/testkit-sqlite) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/testkit-sqlite) | SQLite-specific CTE rewriting and fixture validation. In-memory testing with `better-sqlite3`. |\n\n### Adapter Package Spaces\n\n`driver-adapter-*` packages are production runtime driver adapters.\nThey handle driver mechanics such as named-parameter compilation, placeholder conversion, and row-result normalization without owning ORM behavior or fixture rewriting.\n\n`testkit-adapter-*` packages are test-only adapters that connect concrete drivers to ZTD/testkit fixture rewriting.\n`@rawsql-ts/adapter-node-pg` currently belongs to that testkit adapter role despite its legacy name.\nThe planned rename path is to add a non-breaking alias such as `@rawsql-ts/testkit-adapter-node-postgres`, then document `@rawsql-ts/adapter-node-pg` as the legacy compatibility surface.\n\n### Evidence\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [@rawsql-ts/test-evidence-core](./packages/test-evidence-core) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/test-evidence-core) | Core schema and storage model for deterministic test evidence. |\n| [@rawsql-ts/test-evidence-renderer-md](./packages/test-evidence-renderer-md) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/test-evidence-renderer-md) | Markdown renderer for saved test evidence reports. |\n\n### Documentation\n\n| Package | Version | Description |\n|---------|---------|-------------|\n| [@rawsql-ts/ddl-docs-cli](./packages/ddl-docs-cli) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/ddl-docs-cli) | CLI that generates Markdown table definition docs from DDL files. |\n| [@rawsql-ts/ddl-docs-vitepress](./packages/ddl-docs-vitepress) | ![npm](https://img.shields.io/npm/v/@rawsql-ts/ddl-docs-vitepress) | Scaffold generator for VitePress-based database schema documentation sites. |\n\n## Architecture\n\n```text\nrawsql-ts (core)\n├─ @rawsql-ts/sql-grep-core\n├─ @rawsql-ts/executor\n├─ @rawsql-ts/driver-adapter-core\n├─ @rawsql-ts/testkit-core\n│  ├─ @rawsql-ts/testkit-postgres\n│  │  └─ @rawsql-ts/adapter-node-pg\n│  └─ @rawsql-ts/testkit-sqlite\n├─ @rawsql-ts/ddl-docs-cli\n│  └─ @rawsql-ts/ddl-docs-vitepress\n└─ consumed by Ashiba for CLI workflows\n```\n\n## Quick Start\n\n```bash\nnpm install rawsql-ts\n```\n\nSee the [Core Package Documentation](./packages/core/README.md) for usage examples and API reference. For reusable AST-based impact analysis, see [@rawsql-ts/sql-grep-core](./packages/sql-grep-core). For CLI scaffolding and SQL lifecycle workflows, use [Ashiba](https://github.com/mk3008/ashiba).\n\n## Intent and Procedure\n\nTreat each query as one unit: 1 SQL file / 1 QuerySpec / 1 repository entrypoint / 1 DTO.\n\nKeep handwritten SQL assets close to each feature in `src/features/\u003cfeature\u003e/queries/\u003cquery\u003e/` so the SQL, boundary contract, and query-local tests stay in one place.\n\nUse this repo by treating DDL and SQL as source assets, and generated specs, repositories, and tests as downstream artifacts that must stay in sync.\n\nProcedure: `DDL -\u003e SQL -\u003e generate -\u003e wire -\u003e test`.\n\nFor a step-by-step example, see the SQL-first tutorial above.\n\n## Getting Started with AI\n\nIf you are using an AI coding agent, start with a short prompt that sets only the minimum project shape and domain language. You do **not** need to explain package-manager setup in that prompt.\n\nOptional Docker helper:\n\nIf you want a local PostgreSQL 18 instance for ZTD tests, use a tiny compose file like this:\n\n```yaml\nservices:\n  postgres:\n    image: postgres:18\n    environment:\n      POSTGRES_USER: ztd\n      POSTGRES_PASSWORD: ztd\n      POSTGRES_DB: ztd\n    ports:\n      - \"5432:5432\"\n    volumes:\n      - ztd-postgres-data:/var/lib/postgresql/data\n\nvolumes:\n  ztd-postgres-data:\n```\n\nThen run `docker compose up -d` and point `ZTD_DB_URL` at that database for the fixture-backed rewrite path.\n\n## Online Demo\n\n[Try rawsql-ts in your browser](https://mk3008.github.io/rawsql-ts/)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk3008%2Frawsql-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmk3008%2Frawsql-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk3008%2Frawsql-ts/lists"}