Payload CMS Release: Release 0.15.4

TL;DR

Payload CMS v0.15.4 introduces significant enhancements to field validation with extended function arguments, adds filtering capabilities for relationship and upload fields, improves search functionality, and fixes several bugs. This release focuses on giving developers more control over data validation and relationships while improving performance and user experience.

Highlight of the Release

• Extended validation function arguments providing access to sibling data and field configuration
• New filterOptions capability for relationship and upload fields in the admin UI
• Enhanced search with multi-word 'like' operator and exact-match 'contains' operator
• Support for custom CSS classes on row, block, and array fields
• Customizable Pino logger options during initialization

Migration Guide

Extended Validation Function Arguments

Validation functions now receive additional arguments. The new signature is:

type ValidateFunction = (
  value: any, 
  options: {
    siblingData: Record<string, any>,
    data: Record<string, any>,
    field: Field,
    operation: 'create' | 'update',
    // ... other arguments
  }
) => string | true;

If you're using custom validation functions, you can now access sibling data and field configuration directly through these arguments.

Relationship and Upload Field Filtering

To filter relationship or upload field options in the admin UI, use the new filterOptions property:

{
  name: 'relatedPosts',
  type: 'relationship',
  relationTo: 'posts',
  filterOptions: {
    // Add conditions to filter available options
    category: {
      equals: 'news'
    }
  }
}

Search Operators

The like operator now supports searching by multiple words. For exact string matching, use the new contains operator:

// Searches for documents containing both "hello" and "world" anywhere
{
  title: {
    like: 'hello world'
  }
}

// Searches for documents containing exactly "hello world"
{
  title: {
    contains: 'hello world'
  }
}

Upgrade Recommendations

This is a minor release with significant feature additions but no breaking changes. All users are encouraged to upgrade to benefit from the new validation capabilities, relationship filtering, and bug fixes.

To upgrade:

1. Update your Payload dependency to v0.15.4:

   npm install [email protected]
   # or
   yarn add [email protected]
   

2. Review the new features, especially if you're using custom validation functions or relationship fields, to take advantage of the new capabilities.

3. Test your application thoroughly after upgrading, particularly if you rely on field validation or relationship fields.

Bug Fixes

Fixed Issues

• Fixed issue #495 where version numbers were incorrectly appended to ID queries
• Resolved point validation issues for non-required fields and edge cases
• Improved field validation performance by maintaining internal validation state

Performance Optimizations

• Optimized getDataByPath and getSiblingData functions
• Revised when field validation is run to improve efficiency
• Maintained internal field validation for better performance

New Features

Extended Validation Function Arguments

Validation functions now receive extended arguments including sibling data and field configuration, allowing for more complex and contextual validation rules. This enables validations that depend on other field values or need access to the complete field configuration.

Relationship and Upload Field Filtering

• Added filterOptions capability to relationship fields, allowing developers to dynamically filter available options in the admin UI
• Extended the same filtering functionality to upload fields
• Implemented reusable relationship filters in validation functions

Search Enhancements

• Improved the like operator to search by multiple words
• Added new contains operator for exact string matching

UI Customization

• Added support for custom CSS classes on row, block, and array fields via the className config property
• Enables more granular styling control in the admin interface

Logger Configuration

• Added ability to pass custom Pino logger options during Payload initialization
• Provides more control over logging behavior and output formatting

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Validation Performance

• Optimized validation extended arguments processing
• Improved efficiency of getDataByPath and getSiblingData functions
• Revised the timing of field validation execution for better performance

Search Optimization

• Enhanced the like operator to handle multiple words efficiently
• Added optimized contains operator for exact string matching

Internal Improvements

• Maintained field validation internally for improved speed
• Optimized how validation arguments are passed throughout the system

Impact Summary

Payload CMS v0.15.4 significantly enhances the developer experience by providing more powerful validation capabilities through extended function arguments. This allows for more complex and contextual validation rules that can access sibling data and field configurations.

The addition of filtering options for relationship and upload fields improves content management by allowing developers to dynamically control which options are available to editors based on various conditions. This creates a more tailored and efficient editing experience.

Search functionality has been improved with enhanced like operator supporting multi-word searches and a new contains operator for exact matching, making content retrieval more flexible and precise.

UI customization gets a boost with support for custom CSS classes on structural elements like rows, blocks, and arrays, giving developers more control over the admin interface appearance.

The release also addresses several bugs, particularly around ID queries and validation edge cases, while optimizing performance in key areas like field validation and data retrieval.

Full Release Notes