v1.0.0-alpha.9

This release focuses heavily on TypeScript type safety and inference improvements, specifically targeting nested projections and query result mapping.

✨ Features

Documentation Improvements & Advanced Guides

Completely revamped the documentation structure and added a suite of deep-dive guides for production-grade development:

• Mastering Graph Relations: Advanced many-to-many patterns, edge properties, and high-performance FROM clause path traversal.
• Security & Permissions: Row-level security (RLS) patterns using $auth for table and field-level protection.
• Testing Strategies: Ultra-fast unit testing workflows using the SurrealDB mem:// engine and @surrealdb/node.
• Common Patterns: Architectural recipes for singletons, tagging systems, recursive hierarchies, and polymorphic links.
• Migrations & Schema Sync: Best practices for the CLI pull/push/diff workflow and CI/CD integration.

CLI Unified Log Levels

Introduced a centralized --log-level flag (silent, normal, debug) across all CLI commands.

Interactive CLI Prompts

The CLI now provides interactive prompts for database connections if flags are omitted, making it more convenient for manual usage.

Deeply Nested Type Inference

The type signatures for Table.select() and the FieldSelect utility have been entirely rewritten to support infinite-depth schema awareness.

When projecting complex structures, TypeScript will now provide full autocompletion and strict validation for:

• Nested Field.object() properties
• Linked tables via Field.record()
• Array projections like Field.array(Field.object({...}))

Example:

const posts = await Post.select(db, {
  select: {
    title: true, // Primitive
    author: { name: true, email: true }, // Infers User schema across Record link
    metadata: {
      category: true,
      history: { date: true } // Infers Array Element schema
    }
  }
});

// `posts` is strictly typed as:
// Array<{ title: string, author: { name: string, email: string }, metadata: { category: string, history: Array<{ date: string }> } }>

If you specify an unknown field inside a nested object, the TypeScript compiler will now correctly reject it:

const posts = await Post.select(db, {
  select: {
    author: { invalidField: true } // ❌ TypeScript Error!
  }
});

🔧 Improvements

Strict only: true Return Types

The .select() method now provides precise return type narrowing when using the only: true query option. When specified alongside field projections (select:) or exclusions (omit:), TypeScript will correctly infer the result as a single object (or undefined) instead of an array of objects.

const singlePost = await Post.select(db, {
  select: { title: true, views: true },
  from: post.id,
  only: true, // Narrows the return type
});
// Type: { title: string; views: number } | undefined

Wildcard Selection Overrides

When using the * wildcard to select all fields on a table, you can now explicitly declare subselections without breaking type inference. Explicitly declared keys will cleanly override the base wildcard types.

const results = await Post.select(db, {
  select: {
    "*": true, // Fetch all fields
    author: { name: true } // But strictly project the 'author' relation down to just `name`
  }
});

// Result merges inferShape<PostFields> but narrows `author: { name: string }`

Enhanced SurrealDB Feature Support

The Capabilities Matrix has been updated to reflect full support for:

• Table Views (AS SELECT): Define projected views directly in your schema.
• Changefeeds: Configure durations and original data inclusion.
• Record References: Support for ON DELETE actions (CASCADE, REJECT, etc.) in Field.record.

Explicit id Projection

The FieldSelect utility now officially permits manually specifying id: true alongside standard schema fields, and correctly resolves the output type to the table’s RecordId.

const results = await Post.select(db, {
  select: { id: true, title: true }
});
// Result strictly includes `id: RecordId<"post">`

🐛 Bug Fixes

• CLI: unreal init will now correctly install @types/node (or @types/bun if using Bun) as a dev dependency to prevent TypeScript unresolved module errors on fresh setups.
• CLI Examples: Fixed an outdated query signature in the generated example Post class (order changed to orderBy).