Add SDD architecture docs for dbtype

Phase 0 architecture specification following the alkdev documentation
pattern from @alkdev/flowgraph. Documents the validated architecture
(UJSX elements → Type.Module → Drizzle hosts) based on e2e probe results.

Docs added:
- README: Project overview, architecture, current state
- architecture/README: Index, design decisions, relationships
- architecture/schema: Type.Module as bundle, construction, serialization
- architecture/hosts: HostConfig per dialect, column mapping, symbolic defaults
- architecture/elements: UJSX element types, props, function components
- architecture/module: Module mechanics, format registration, diffing
- architecture/repo-adapter: from-dbtype operations adapter (phase 2)
- architecture/build-distribution: Package structure, exports
- architecture/open-questions: 10 open questions across all topics
- ADRs 001-005: UJSX as IR, Type.Module, HostConfig, format, repo adapter
This commit is contained in:
2026-05-22 11:34:58 +00:00
parent 6fe84e1a53
commit dd2ec9df3c
14 changed files with 1447 additions and 48 deletions

View File

@@ -0,0 +1,91 @@
---
status: draft
last_updated: 2026-05-22
---
# Build & Distribution
Package structure, exports, dependencies, and tree-shaking strategy.
## Package
- **Name**: `@alkdev/dbtype`
- **Type**: ESM with CJS fallback
- **Peer dependencies**: `@alkdev/typebox >=0.34.49`, `@alkdev/ujsx >=0.1.0`, `drizzle-orm >=0.36.0`
- **Dev dependencies**: All three peer deps for testing, plus `tsx`, `vitest`, `typescript`
## Sub-path Exports
```json
{
"exports": {
".": {
"import": { "types": "./index.d.mts", "default": "./index.mjs" },
"require": { "types": "./index.d.cjs", "default": "./index.cjs" }
},
"/core": {
"import": { "types": "./core/index.d.mts", "default": "./core/index.mjs" },
"require": { "types": "./core/index.d.cjs", "default": "./core/index.cjs" }
},
"/sqlite": {
"import": { "types": "./sqlite/index.d.mts", "default": "./sqlite/index.mjs" },
"require": { "types": "./sqlite/index.d.cjs", "default": "./sqlite/index.cjs" }
},
"/pg": {
"import": { "types": "./pg/index.d.mts", "default": "./pg/index.mjs" },
"require": { "types": "./pg/index.d.cjs", "default": "./pg/index.cjs" }
},
"/mysql": {
"import": { "types": "./mysql/index.d.mts", "default": "./mysql/index.mjs" },
"require": { "types": "./mysql/index.d.cjs", "default": "./mysql/index.cjs" }
}
}
}
```
Tree-shaking: Users who only use SQLite import `/sqlite` and never pull in PG or MySQL column builders.
## Source Structure
```
src/
core/
elements.ts # h() wrappers, createComponent for table/column/index/fk
schema.ts # extractTable, createSelectSchema, createInsertSchema, createUpdateSchema
module.ts # buildModule, module construction helpers
column-types.ts # DbColumnType union, colToTypeBox mapping
defaults.ts # Symbolic default resolution ('now', 'uuid', 'autoincrement')
guards.ts # Type guards for element types
index.ts
hosts/
sqlite.ts # HostConfig for drizzle-orm/sqlite-core
pg.ts # HostConfig for drizzle-orm/pg-core
mysql.ts # HostConfig for drizzle-orm/mysql-core
repo/
from-dbtype.ts # FromDbType adapter for @alkdev/operations (phase 2)
filters.ts # Filter schema generation per column type
handlers.ts # CRUD handler generation
index.ts # Re-exports core
```
## Dependencies
```
@alkdev/dbtype
├── @alkdev/typebox (peer) # Type.Module, Type.Ref, Value.Check, FormatRegistry
├── @alkdev/ujsx (peer) # h, createComponent, HostConfig, createRoot
└── drizzle-orm (peer) # Dialect-specific column builders (per sub-path)
```
The core package (`@alkdev/dbtype/core`) depends only on `@alkdev/typebox` and `@alkdev/ujsx`. The dialect modules (`/sqlite`, `/pg`, `/mysql`) add `drizzle-orm` as a peer dependency (scoped to the specific dialect sub-module).
## Constraints
- **Core must not import from drizzle-orm** — the core (elements, schema extraction, module) is dialect-agnostic
- **Dialect modules must not import from each other** — SQLite host doesn't pull in PG types
- **Build is ESM-first** — CJS is generated as a fallback for compatibility
## References
- Typemap sub-path exports pattern: `docs/research/typemap-architecture.md`
- Current package: `package.json`