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:
91
docs/architecture/build-distribution.md
Normal file
91
docs/architecture/build-distribution.md
Normal 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`
|
||||
Reference in New Issue
Block a user