feat: AppSheet Field Type Support and Validation Enhancement (SOSO-247)

[wagnert]

Summary

Implementation of SOSO-247: AppSheet Field Type Support and Validation Enhancement - a breaking change for v2.0.0.

This PR replaces generic TypeScript types with 27 AppSheet-specific field types and implements comprehensive validation for all field types.

Breaking Changes ⚠️

This is a major version bump to v2.0.0 with the following breaking changes:

• ❌ Generic types (string, number, boolean, date, array, object) removed
• ✅ Replaced with 27 AppSheet-specific types (Email, URL, Phone, Enum, EnumList, Percent, etc.)
• ❌ Shorthand field format (email: string) removed
• ✅ Only full object format supported (email: { type: 'Email', required: true })
• ❌ Property enum renamed to allowedValues

See MIGRATION.md for complete migration guide.

Implementation Overview

Phase 1: Type System Extension

• Added 27 AppSheet field types across 7 categories
• Updated AppSheetFieldType union type
• Enhanced FieldDefinition interface with allowedValues, referencedTable, appSheetConfig
• Removed backward compatibility for clean v2.0.0 release

Phase 2: Validation Enhancement

• Extracted validation logic into modular classes:
  • BaseTypeValidator - JavaScript primitive validation
  • FormatValidator - Format-specific validation (Email, URL, Phone, Date patterns, Percent range)
  • AppSheetTypeValidator - Main orchestrator for all AppSheet types
• Comprehensive validation for all 27 field types
• Clear, descriptive error messages with field names and row indices

Phase 3: SchemaInspector Enhancement

• Smart enum detection heuristic (≤10 unique values OR <20% unique ratio)
• Automatic allowedValues extraction for Enum/EnumList fields
• Multi-row analysis (up to 100 rows) for better type inference
• Pattern detection for Email, URL, Phone, Date, DateTime, Percent

Phase 4: Documentation

• Created comprehensive MIGRATION.md guide
• Updated CLAUDE.md with new type system
• Added validation examples and breaking changes documentation

Phase 5: Testing

• 126 tests total (all passing ✅)
• 81.88% coverage overall
• 100% coverage for DynamicTable.ts
• 62 new SchemaInspector tests
• 44 new DynamicTable tests including integration tests

Test Results

---------------------------|---------|----------|---------|---------|---------------------
File                       | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s   
---------------------------|---------|----------|---------|---------|---------------------
All files                  |   81.88 |    74.17 |   77.89 |   81.84 |                     
 cli                       |   72.07 |    78.18 |   57.14 |   71.96 |                     
  SchemaInspector.ts       |   72.07 |    78.18 |   57.14 |   71.96 |                     
 client                    |   84.06 |    57.81 |      86 |   84.26 |                     
  DynamicTable.ts          |     100 |      100 |     100 |     100 | ✅ PERFECT
  AppSheetClient.ts        |   65.21 |    23.52 |   72.22 |   66.17 |                     
  MockAppSheetClient.ts    |   93.58 |       95 |   90.47 |   93.42 |                     
 utils/validators          |    93.1 |     87.3 |   88.88 |   92.77 |                     
---------------------------|---------|----------|---------|---------|---------------------

AppSheet Field Types

Core Types

• Text, Number, Date, DateTime, Time, Duration, YesNo

Specialized Text Types

• Name, Email, URL, Phone, Address

Specialized Number Types

• Decimal, Percent, Price

Selection Types

• Enum, EnumList

Media Types

• Image, File, Drawing, Signature

Tracking Types

• ChangeCounter, ChangeTimestamp, ChangeLocation

Reference Types

• Ref, RefList

Special Types

• Color, Show

Migration Example

# Before (v1.x)
fields:
  email: string
  status:
    type: string
    enum: ["Active", "Inactive"]

# After (v2.0.0)
fields:
  email:
    type: Email
    required: true
  status:
    type: Enum
    required: true
    allowedValues: ["Active", "Inactive"]

Validation Examples

// Email validation
await table.add([{ email: 'invalid' }]);
// ❌ Error: Field "email" must be a valid email address

// Enum validation
await table.add([{ status: 'Unknown' }]);
// ❌ Error: Field "status" must be one of: Active, Inactive, Pending

// Percent range validation
await table.add([{ discount: 1.5 }]);
// ❌ Error: Field "discount" must be between 0.00 and 1.00

Commits

• feat: add SOSO-247 requirements document
• feat(SOSO-247): implement AppSheet field types and validation (Phase 1)
• feat(SOSO-247): extract validation logic to separate validator classes (Phase 2)
• feat(SOSO-247): enhance SchemaInspector with smart type detection (Phase 3)
• docs(SOSO-247): add comprehensive documentation for v2.0.0 (Phase 4)
• test: add comprehensive tests for Phase 5 (SOSO-247)

Checklist

• All tests passing (126/126 ✅)
• Test coverage >80% (81.88%)
• DynamicTable 100% coverage
• Documentation updated (MIGRATION.md, CLAUDE.md)
• Breaking changes documented
• Type definitions complete
• Validation implemented for all types
• CLI SchemaInspector enhanced
• No build errors

Related

• JIRA: SOSO-247
• Type: Breaking Change / Feature
• Version: 2.0.0

🤖 Generated with Claude Code