fix(orm): coalesce NULL → '' in single-field _ftsRelevance ORDER BY

`to_tsvector(NULL)` returns NULL and `ts_rank(NULL, ...)` therefore
returns NULL — under Postgres's default `NULLS FIRST` for `ORDER BY DESC`
this would surface NULL-valued rows ahead of any matching ones, an
asymmetry with the multi-field path where `concat_ws(' ', ...)` already
skips NULLs and yields a 0.0 rank. Coalescing the field to `''` aligns
the two paths.

Adds `subtitle: String? @fullText` to the test fixture and a regression
test that orders a NULL-subtitle row against a matching one — without
the fix, the NULL row ranks first under DESC.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ymc9

packages/orm/src/client/crud/dialects/postgresql.ts

@@ -707,11 +707,15 @@ export class PostgresCrudDialect<Schema extends SchemaDef> extends LateralJoinDi
         const q = sql.val(search);
 
         // Document expression: a single field, or `concat_ws` of all fields when
-        // multi-field. `concat_ws` skips NULL arguments natively. Multi-field uses
-        // a single ts_rank over the combined document (matches Prisma; ensures
-        // AND queries match terms spread across fields).
+        // multi-field. The single-field path coalesces NULL → '' so `ts_rank`
+        // returns 0.0 (not NULL) for NULL-valued rows, matching the null-skipping
+        // behavior `concat_ws` already provides on the multi-field path.
+        // Multi-field uses a single ts_rank over the combined document (matches
+        // Prisma; ensures AND queries match terms spread across fields).
         const document =
-            fieldRefs.length === 1 ? fieldRefs[0]! : sql`concat_ws(' ', ${sql.join(fieldRefs)})`;
+            fieldRefs.length === 1
+                ? sql`coalesce(${fieldRefs[0]!}, '')`
+                : sql`concat_ws(' ', ${sql.join(fieldRefs)})`;
 
         if (config === undefined) {
             // No regconfig — Postgres uses default_text_search_config.

tests/e2e/orm/client-api/full-text-search.test.ts

@@ -190,6 +190,28 @@ describe.skipIf(provider !== 'postgresql')('Full-text search tests', () => {
         expect(results[0]!.title).toBe('A cat and a dog');
     });
 
+    it('single-field _ftsRelevance on a nullable @fullText field tolerates NULL rows', async () => {
+        // `subtitle` is `String? @fullText`. A row whose subtitle is NULL must
+        // not break the orderBy expression — `to_tsvector(NULL)` returns NULL
+        // and `ts_rank(NULL, ...)` returns NULL, which would otherwise place
+        // those rows at the front under ASC. The single-field path coalesces
+        // NULL → '' so `ts_rank` returns 0.0 instead, matching how the
+        // multi-field `concat_ws` path already handles NULL inputs.
+        const created = await Promise.all([
+            client.article.create({ data: { title: 't1', body: 'b1', subtitle: 'cat' } }),
+            client.article.create({ data: { title: 't2', body: 'b2', subtitle: null } }),
+        ]);
+        const ids = created.map((r) => r.id);
+        const results = await client.article.findMany({
+            where: { id: { in: ids } },
+            orderBy: [
+                { _ftsRelevance: { fields: ['subtitle'], search: 'cat', sort: 'desc' } },
+                { id: 'asc' },
+            ],
+        });
+        expect(results.map((r) => r.subtitle)).toEqual(['cat', null]);
+    });
+
     it('orderBy with config option', async () => {
         const results = await client.article.findMany({
             where: { body: { fts: { search: 'run', config: 'english' } } },
@@ -338,14 +360,16 @@ describe.skipIf(provider !== 'postgresql')('Full-text search tests', () => {
     it('rejects _ftsRelevance on a non-@fullText field', async () => {
         // `_ftsRelevance.fields` is typed as an enum of `@fullText` field names
         // only — `notes` is rejected with a precise enum-mismatch error that
-        // also confirms the enum lists exactly `title` and `body`.
+        // also confirms the enum lists exactly the three `@fullText` fields.
         await expect(
             client.article.findMany({
                 orderBy: {
                     _ftsRelevance: { fields: ['notes' as any], search: 'foo', sort: 'desc' },
                 } as any,
             }),
-        ).rejects.toThrow(/expected one of "title"\|"body"\s*at\s*"orderBy\._ftsRelevance\.fields/i);
+        ).rejects.toThrow(
+            /expected one of "title"\|"body"\|"subtitle"\s*at\s*"orderBy\._ftsRelevance\.fields/i,
+        );
     });
 
     // ---------------------------------------------------------------

tests/e2e/orm/schemas/full-text-search/schema.ts

@@ -33,6 +33,13 @@ export class SchemaType implements SchemaDef {
                     fullText: true,
                     attributes: [{ name: "@fullText" }] as readonly AttributeApplication[]
                 },
+                subtitle: {
+                    name: "subtitle",
+                    type: "String",
+                    optional: true,
+                    fullText: true,
+                    attributes: [{ name: "@fullText" }] as readonly AttributeApplication[]
+                },
                 notes: {
                     name: "notes",
                     type: "String",

tests/e2e/orm/schemas/full-text-search/schema.zmodel

@@ -4,8 +4,9 @@ datasource db {
 }
 
 model Article {
-    id    Int     @id @default(autoincrement())
-    title String  @fullText
-    body  String  @fullText
-    notes String? // not full-text-searchable
+    id       Int     @id @default(autoincrement())
+    title    String  @fullText
+    body     String  @fullText
+    subtitle String? @fullText
+    notes    String? // not full-text-searchable
 }