v2.1.2 - Automatic JSONB Type Casting & Type Hint Improvements

New Features

Automatic JSONB Type Casting for PostgreSQL

Version 2.1.2 introduces intelligent automatic type casting for JSONB columns in PostgreSQL, dramatically simplifying how you work with JSON data.

What's New:

Plain JavaScript objects are now automatically detected and cast as JSONB in PostgreSQL queries - no more manual JSON.stringify() or explicit ::jsonb casts needed!

// Before v2.1.2 - Manual approach
const metadata = { role: 'admin', permissions: ['read', 'write'] }
await client.query('INSERT INTO users (metadata) VALUES (:metadata::jsonb)', {
  metadata: JSON.stringify(metadata)
})

// Now in v2.1.2 - Automatic!
const metadata = { role: 'admin', permissions: ['read', 'write'] }
await client.query('INSERT INTO users (metadata) VALUES (:metadata)', {
  metadata: metadata // Automatically serialized and cast as ::jsonb
})

How It Works:

• Detects plain JavaScript objects (not Buffers, Dates, Arrays, or Data API objects)
• Automatically serializes to JSON string
• Appends ::jsonb cast to the parameter in PostgreSQL queries
• Adds JSON typeHint to the Data API for proper handling

Benefits:

• Cleaner Code - No more manual JSON.stringify() calls
• Type Safety - Automatic detection prevents common mistakes
• Backwards Compatible - Explicit casts still work and take precedence
• Works Everywhere - Supports nested objects, complex structures

When Automatic Casting Applies:

• ✅ Plain objects: { key: 'value' }
• ✅ Nested objects: { user: { name: 'Alice' } }
• ✅ Complex structures: { data: { nested: { deep: true } } }
• ❌ Buffers: Buffer.from('data')
• ❌ Dates: new Date()
• ❌ Arrays: [1, 2, 3]
• ❌ Already-formatted Data API objects: { stringValue: 'text' }

Explicit Casting Still Supported:

You can still use explicit casts when needed (e.g., for UUID, custom types):

// Explicit cast for UUID
await client.query('INSERT INTO users (id) VALUES (:id)', [
  { name: 'id', value: uuid, cast: 'uuid' }
])

// Or inline casting
await client.query('INSERT INTO users (id) VALUES (:id::uuid)', { id: uuid })

Note: Explicit casts always take precedence over automatic casting.

Bug Fixes

Removed Automatic Type Hint Detection for Specific Types (Issue #144)

Fixed an issue where automatic type hint detection was causing problems with VARCHAR columns that happened to contain UUID-formatted strings, date strings, or other special formats.

What Changed:

• Removed automatic UUID type hint detection for UUID-formatted strings
• Removed automatic DATE/TIME/TIMESTAMP type hint detection for date strings
• Removed automatic DECIMAL type hint detection for numeric strings
• Type hints are now only added for:
  • Date objects → TIMESTAMP
  • Plain JavaScript objects → JSON (new in this release)

Why This Matters:

Previously, if you had a VARCHAR column storing a UUID-formatted string, the library would automatically add a UUID type hint, causing insertion failures. Now, strings are treated as strings unless you explicitly cast them.

Migration Guide:

If you were relying on automatic type hint detection, you'll need to add explicit casts:

// Before (automatic detection)
await client.query('INSERT INTO users (id) VALUES (:id)', {
  id: '550e8400-e29b-41d4-a716-446655440000' // Auto-detected as UUID
})

// Now (explicit cast required)
await client.query('INSERT INTO users (id) VALUES (:id::uuid)', {
  id: '550e8400-e29b-41d4-a716-446655440000'
})

// Or using cast parameter
await client.query('INSERT INTO users (id) VALUES (:id)', [
  { name: 'id', value: '550e8400-e29b-41d4-a716-446655440000', cast: 'uuid' }
])

Code Quality Improvements

• Applied consistent code formatting to PostgreSQL compatibility layer
• Improved code readability with better line breaks and spacing

Documentation Updates

• Added comprehensive documentation for automatic JSONB type casting
• Updated Type-Casting section with clear examples
• Updated PostgreSQL Data Type Support section
• Updated simple examples to showcase new features

Testing

• Added integration tests for automatic JSONB casting
• Added tests for typeHint validation
• Updated ORM integration tests (Drizzle, Kysely)
• Re-enabled previously failing empty array tests

Upgrade Instructions

npm install data-api-client@2.1.2

Or update your package.json:

{
  "dependencies": {
    "data-api-client": "^2.1.2"
  }
}

Feedback

I'd love to hear your feedback! If you encounter any issues or have suggestions for improvement, please open an issue.

---

Full Changelog: v2.1.1...v2.1.2