refactor: star rating (#26357)

* refactor: star rating

* transform rating 0 to null in controller dto

* migrate rating 0 to null

* deprecate rating -1

* rating type annotation

* update Rating type

server/src/dtos/asset.dto.ts

@@ -1,5 +1,5 @@
 import { ApiProperty } from '@nestjs/swagger';
-import { Type } from 'class-transformer';
+import { Transform, Type } from 'class-transformer';
 import {
   IsArray,
   IsDateString,
@@ -16,6 +16,7 @@ import {
   ValidateIf,
   ValidateNested,
 } from 'class-validator';
+import { HistoryBuilder, Property } from 'src/decorators';
 import { BulkIdsDto } from 'src/dtos/asset-ids.response.dto';
 import { AssetType, AssetVisibility } from 'src/enum';
 import { AssetStats } from 'src/repositories/asset.repository';
@@ -56,12 +57,19 @@ export class UpdateAssetBase {
   @IsNotEmpty()
   longitude?: number;
 
-  @ApiProperty({ description: 'Rating' })
-  @Optional()
+  @Property({
+    description: 'Rating in range [1-5], or null for unrated',
+    history: new HistoryBuilder()
+      .added('v1')
+      .stable('v2')
+      .updated('v2.6.0', 'Using -1 as a rating is deprecated and will be removed in the next major version.'),
+  })
+  @Optional({ nullable: true })
   @IsInt()
   @Max(5)
   @Min(-1)
-  rating?: number;
+  @Transform(({ value }) => (value === 0 ? null : value))
+  rating?: number | null;
 
   @ApiProperty({ description: 'Asset description' })
   @Optional()

server/src/dtos/search.dto.ts

@@ -2,7 +2,7 @@ import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { Type } from 'class-transformer';
 import { IsInt, IsNotEmpty, IsString, Max, Min } from 'class-validator';
 import { Place } from 'src/database';
-import { HistoryBuilder } from 'src/decorators';
+import { HistoryBuilder, Property } from 'src/decorators';
 import { AlbumResponseDto } from 'src/dtos/album.dto';
 import { AssetResponseDto } from 'src/dtos/asset-response.dto';
 import { AssetOrder, AssetType, AssetVisibility } from 'src/enum';
@@ -103,12 +103,21 @@ class BaseSearchDto {
   @ValidateUUID({ each: true, optional: true, description: 'Filter by album IDs' })
   albumIds?: string[];
 
-  @ApiPropertyOptional({ type: 'number', description: 'Filter by rating', minimum: -1, maximum: 5 })
-  @Optional()
+  @Property({
+    type: 'number',
+    description: 'Filter by rating [1-5], or null for unrated',
+    minimum: -1,
+    maximum: 5,
+    history: new HistoryBuilder()
+      .added('v1')
+      .stable('v2')
+      .updated('v2.6.0', 'Using -1 as a rating is deprecated and will be removed in the next major version.'),
+  })
+  @Optional({ nullable: true })
   @IsInt()
   @Max(5)
   @Min(-1)
-  rating?: number;
+  rating?: number | null;
 
   @ApiPropertyOptional({ description: 'Filter by OCR text content' })
   @IsString()