typhex 0.1.0-alpha.0

package/docs/reference/architecture.md

@@ -0,0 +1,83 @@
+# Architecture
+
+## Query Pipeline
+
+Every Typhex query follows the same pipeline regardless of which mode (runtime or transformer) is used:
+
+```
+Arrow function
+      │
+      ▼
+┌──────────────────────────────────────────────────┐
+│  Parser (runtime: Acorn)  or  Transformer (tsc)  │
+└──────────────────────────────────────────────────┘
+      │
+      ▼  Intermediate Representation (IR)
+┌─────────────────────┐
+│  SQL Compiler       │  dialect-specific: SQLite or PostgreSQL
+└─────────────────────┘
+      │
+      ▼  SQL + parameters
+┌─────────────────────┐
+│  Driver             │  better-sqlite3 / pg / custom
+└─────────────────────┘
+      │
+      ▼
+   Database
+```
+
+Both modes produce the same IR and therefore the same SQL output. See [TypeScript Transformer](/guide/typescript-transformer) for setup.
+
+## Intermediate Representation (IR)
+
+The IR is a tree of typed nodes that describes a predicate or projection in a database-agnostic form. The SQL compiler walks this tree to produce parameterized SQL.
+
+Key IR node types:
+
+| Node       | Description                                                   |
+| ---------- | ------------------------------------------------------------- |
+| `IrBinary` | Binary operator: `=`, `!=`, `>`, `>=`, `<`, `<=`, `AND`, `OR` |
+| `IrUnary`  | Unary operator: `NOT`                                         |
+| `IrMember` | Column access: `u.name` → `"name"`                            |
+| `IrConst`  | Literal value: number, string, boolean, null                  |
+| `IrParam`  | Closure variable: bound at execution time                     |
+| `IrCall`   | Method call: `startsWith`, `endsWith`, `includes`             |
+| `IrIn`     | Array membership: `id IN (...)`                               |
+| `IrExists` | EXISTS subquery (for `oneToMany` `.some()` predicates)        |
+| `IrSelect` | Projection descriptor: paths and aliases                      |
+
+## Driver Abstraction
+
+The `Driver` interface is the boundary between the query engine and the database:
+
+```ts
+interface Driver {
+  readonly dialect: Dialect;
+  connect(): Promise<Connection>;
+  createTrx(conn: Connection, options?: TransactionOptions): Trx;
+  close(): Promise<void>;
+}
+
+interface Connection {
+  readonly dialect: Dialect;
+  execute(sql: string, params?: unknown[]): Promise<ExecuteResult>;
+  release(): Promise<void>;
+}
+```
+
+Built-in drivers wrap `better-sqlite3` and `pg.Pool`. Implementing this interface (and a matching SQL dialect) is enough to add a new database backend.
+
+## SQL Dialects
+
+The shared IR is compiled to SQL by dialect modules. The two built-in dialects (SQLite and PostgreSQL) share most logic and differ mainly in:
+
+- Parameter placeholder style (`?` vs `$1`, `$2`, …)
+- `INSERT ... RETURNING` support (PostgreSQL only)
+- `ON CONFLICT` syntax variations
+- Database-specific aggregates (`groupConcat` vs `stringAgg` / `arrayAgg` / `jsonAgg`)
+
+## Schema Registry
+
+`Entity()` registers each table definition in a global registry. When `new Db(driver)` is called, it sets the driver as the default for all registered entities, and `db.migrate()` iterates the registry to create missing tables.
+
+This design means you don't need to pass a `db` instance to every query — the driver is resolved automatically from the registry.

package/docs/release-checklist.md

@@ -0,0 +1,55 @@
+# Release Checklist
+
+Use this checklist before tagging a production release.
+
+## API
+
+- Run `npm run api:check` and confirm `etc/typhex.api.md` is unchanged. If the public surface changed intentionally, run `npm run api:update`, review the diff, and commit it alongside the change.
+- Confirm `docs/public-api.md` matches `package.json` exports and `src/index.ts`.
+- Confirm new exports are documented with examples.
+- Confirm internal helpers are not required for common application usage.
+- Add a migration guide for any breaking public API change.
+- Update `CHANGELOG.md` with user-visible changes and any compatibility notes.
+
+## Compatibility
+
+- Run the full test suite on the supported Node.js versions.
+- Run SQLite tests with the bundled `better-sqlite3` driver.
+- Run PostgreSQL integration tests with `TYPHEX_POSTGRES_URL` set.
+- Verify runtime parser mode and transformer mode.
+
+## Package
+
+- Run `npm run release:check`.
+- Run `npm run pack:check` and inspect the tarball contents.
+- Verify `dist/index.d.ts`, `dist/transformer/index.d.ts`, `dist/sqlite.d.ts`, and `dist/postgres.d.ts` are present.
+- Verify the CLI entry `dist/migration/cli.js` exists and is executable.
+- Verify `LICENSE`, `README.md`, `CHANGELOG.md`, and `SECURITY.md` are included.
+- Verify source maps are generated or intentionally omitted.
+- Publish with npm provenance enabled.
+
+## Publish
+
+- Confirm the Git tag matches the package version exactly: `v${package.json.version}`.
+- Push the tag to trigger `.github/workflows/release.yml`.
+- Configure npm authentication before the first tag-triggered release:
+  - preferred: npm trusted publishing for this repository/workflow; or
+  - fallback: an `NPM_TOKEN` GitHub Actions secret with publish permissions.
+- Prerelease versions such as `0.1.0-alpha.0` publish with the npm `alpha` dist-tag.
+- Stable versions publish with the npm `latest` dist-tag.
+- The release workflow skips npm publish and GitHub release creation when the version/tag already exists, so reruns are safe after partial failures.
+
+## Migrations
+
+- Generate a migration from a clean database.
+- Apply pending migrations.
+- Check migration status.
+- Run a no-op generate/status cycle after applying.
+- For PostgreSQL, verify generated SQL against a real database.
+
+## Documentation
+
+- README quick start uses the current `Entity` API.
+- Examples cover SQLite, PostgreSQL, relations, many-to-many, transactions, aggregations, and migrations.
+- Known limitations are listed explicitly.
+- Transformer setup includes TypeScript version expectations.