dbtype/docs/architecture/module.md

status, last_updated

status	last_updated
draft	2026-05-22

Module: Type.Module as the Schema Bundle

Technical details on how dbtype uses Type.Module for schema construction, validation, serialization, and migration.

Overview

dbtype uses @alkdev/typebox's Type.Module as the schema storage and resolution mechanism. A module holds all table schemas, their relations, and derived schemas (insert, update, partial) in a single flat namespace. Type.Ref resolves cross-table references — including circular ones — without import ordering issues.

This document covers the mechanics, constraints, and patterns discovered during architecture probing.

Construction Patterns

Basic Pattern

const defs: Record<string, any> = {
  Users: Type.Object({ id: Type.String({ format: 'uuid' }), name: Type.String() }),
  Tasks: Type.Object({ id: Type.String({ format: 'uuid' }), title: Type.String() }),
}

const M = Type.Module(defs)
const Users = M.Import('Users')

With Relations

defs.UsersRelations = Type.Object({ tasks: Type.Array(Type.Ref('Tasks')) })
defs.TasksRelations = Type.Object({ user: Type.Ref('Users') })

Type.Ref('Users') within the module resolves to the Users schema. No circular import issues.

With Derived Schemas

defs.InsertUsers = Type.Object({ name: Type.String(), email: Type.String() })  // manual
defs.UpdateUsers = Type.Partial(Type.Ref('Users'))  // computed

Incremental Construction

// Build defs incrementally
const defs: Record<string, any> = {}
defs.Users = extractTableSchema(UsersElement)
defs.Tasks = extractTableSchema(TasksElement)

// Add a column later
defs.Users = Type.Object({ ...defs.Users.properties, role: Type.String() })

// Add relations
defs.UsersRelations = Type.Object({ tasks: Type.Array(Type.Ref('Tasks')) })

// Compile when ready
const M = Type.Module(defs)

Validation

Format Registration Required

TypeBox treats format as an annotation by default. To enforce format validation, register custom formats:

import { FormatRegistry } from '@alkdev/typebox'

FormatRegistry.Set('uuid', (value) => /^[0-9a-f]{8}-...$/i.test(value))
FormatRegistry.Set('email', (value) => /^[^@]+@[^@]+\.[^@]+$/.test(value))

After registration, Value.Check enforces these formats.

Validation Pattern

const M = Type.Module(defs)
const Users = M.Import('Users')

// Valid
Value.Check(Users, { id: '550e8400-e29b-41d4-a716-446655440000', name: 'alice', email: 'a@b.com', ... })

// Invalid — Value.Check returns false, Value.Errors provides details
Value.Check(Users, { id: 'bad-uuid', ... })  // false
for (const err of Value.Errors(Users, badData)) { ... }

Serialization

JSON.stringify(M.Import(key)) produces JSON Schema with $defs:

{
  "$defs": {
    "Users": { "$id": "Users", "type": "object", "properties": { ... }, "required": [...] },
    "Tasks": { "$id": "Tasks", "type": "object", "properties": { ... }, "required": [...] },
    "UsersRelations": { "$id": "UsersRelations", "type": "object", "properties": { "tasks": { "type": "array", "items": { "$ref": "Tasks" } } } }
  },
  "$ref": "Users"
}

Key properties:

• Each $defs entry has an $id matching its key
• Type.Ref remains as { "$ref": "Key" } — not inlined
• The entire structure is valid JSON Schema
• All entries in the module are present in $defs (even if only one was imported)

Roundtrip

The serialized form can be parsed back into a schema-like structure. Value.Diff works on these serialized objects to produce structural edit lists.

Migration Diffing

const v1 = JSON.parse(JSON.stringify(M.Import('Users')))

// Modify schema
defs.Users = Type.Object({ ...defs.Users.properties, role: Type.String() })

const M2 = Type.Module(defs)
const v2 = JSON.parse(JSON.stringify(M2.Import('Users')))

const edits = Value.Diff(v1, v2)
// [
//   { type: 'insert', path: '/$defs/Users/properties/role', value: { type: 'string' } },
//   { type: 'update', path: '/$defs/Users/required/3', value: 'role' },
// ]

Edits use JSON Pointer paths. A migration generator can translate these to:

• INSERT for new properties → ALTER TABLE ADD COLUMN
• DELETE for removed properties → ALTER TABLE DROP COLUMN
• UPDATE for type changes → ALTER TABLE ALTER COLUMN TYPE

This is structural diffing, not semantic — it doesn't understand that changing Type.String() to Type.String({ maxLength: 255 }) is a constraint addition, not a type change. Semantic diffing is a future concern.

Cross-Module References

Module.Import() embeds the source module's $defs in the resulting TImport schema. This enables referencing types from another module:

const CommonM = Type.Module({ Uuid: Type.String({ format: 'uuid' }) })
const CommonUuid = CommonM.Import('Uuid')

const AppM = Type.Module({
  User: Type.Object({ id: CommonUuid, name: Type.String() }),
})

However, this nests $defs within $defs (the User's $defs contains CommonUuid's $defs), which increases payload size. For dbtype's use case, keeping everything in a single module is simpler and avoids nesting.

Constraints

• Module entries are computed at construction time — Type.Partial(Type.Ref('Users')) is resolved when the module is built, producing a concrete optional-property object
• Type.Ref outside a module has static: unknown — always use M.Import(key) for proper type inference
• Module keys are a flat namespace — no nested paths like "tables/Users". Table names must be unique within the module.
• Module.Import embeds all $defs — every import carries the full module. This is correct for validation but increases JSON Schema size.
• Symbol properties are lost in JSON.stringify — [Kind], [Hint], etc. are stripped. The serialized form is JSON Schema, not TypeBox schema. Roundtripping requires FromSchema or reconstructed TypeBox objects.

References

• TypeBox Module: @alkdev/typebox/src/type/module/module.ts
• TypeBox Format: @alkdev/typebox/src/type/registry/format.ts
• Probe: scripts/probe-e2e.ts