Better introspection of table relationships

[brainkim]

Summary

• Adds relations() method to navigate both forward and reverse table relations
• Uses WeakMap registry with lazy resolution to handle circular references
• Forward relations come from as, reverse from reverseAs
• Validates uniqueness of relation names per target table

API

const Users = table("users", {
  id: z.string().db.primary(),
  email: z.string().email(),
});

const Posts = table("posts", {
  id: z.string().db.primary(),
  title: z.string(),
  authorId: z.string().db.references(Users, "author", { reverseAs: "posts" }),
});

// Forward relation (many-to-one): Posts -> Users
Posts.relations().author.table           // Users table
Posts.relations().author.fields().email  // Users.email field metadata

// Reverse relation (one-to-many): Users -> Posts
Users.relations().posts.table            // Posts table
Users.relations().posts.fields().title   // Posts.title field metadata

// Chain navigation
Users.relations().posts.fields().author.fields().email  // Back to Users

Relation interface

interface Relation<TargetTable> {
  fields(): TableFields<...>;  // Navigate to related table's fields
  table: TargetTable;          // Direct access to related table
}

Test plan

• Returns empty object for table with no relations
• Returns forward relation from references
• Returns reverse relation when defined with reverseAs
• Returns both forward and reverse relations
• fields() navigates to related table fields
• Supports multiple reverse relations
• Chained navigation through relations
• No reverse relation without reverseAs
• Throws on duplicate reverseAs names for same target
• Throws when reverseAs collides with forward relation name

Closes #18

🤖 Generated with Claude Code