feat: handle PgLiteral in index expressions (#1561)

Co-authored-by: Shinigami <chrissi92@hotmail.de>

Author: brenoepics

src/operations/generalTypes.ts

@@ -24,7 +24,32 @@ export type Value =
 
 export type Type = string | { type: string };
 
-export type Name = string | { schema?: string; name: string };
+export type Name = string | { schema?: string; name: string } | PgLiteralValue;
+
+/**
+ * Type guard for the object form of {@link Name}.
+ *
+ * Note: This only checks shape (presence of a "name" property). It intentionally
+ * does not validate contents.
+ */
+export function isNameObject(
+  val: unknown
+): val is Exclude<Name, string | PgLiteralValue> {
+  return typeof val === 'object' && val !== null && 'name' in val;
+}
+
+/**
+ * Type guard for schema-qualified {@link Name} objects.
+ */
+export function isSchemaNameObject(
+  val: unknown
+): val is { schema: string; name: string } {
+  return (
+    isNameObject(val) &&
+    'schema' in val &&
+    typeof (val as { schema?: unknown }).schema === 'string'
+  );
+}
 
 export interface IfNotExistsOption {
   ifNotExists?: boolean;

src/operations/indexes/createIndex.ts

@@ -1,6 +1,11 @@
 import type { MigrationOptions } from '../../migrationOptions';
 import { toArray } from '../../utils';
-import type { IfNotExistsOption, Name, Reversible } from '../generalTypes';
+import {
+  isNameObject,
+  type IfNotExistsOption,
+  type Name,
+  type Reversible,
+} from '../generalTypes';
 import type { DropIndexOptions } from './dropIndex';
 import { dropIndex } from './dropIndex';
 import type { IndexColumn } from './shared';
@@ -63,7 +68,7 @@ export function createIndex(mOptions: MigrationOptions): CreateIndex {
     const columns = toArray(rawColumns);
 
     const indexName = generateIndexName(
-      typeof tableName === 'object' ? tableName.name : tableName,
+      isNameObject(tableName) ? tableName.name : tableName,
       columns,
       options,
       mOptions.schemalize

src/operations/indexes/shared.ts

@@ -1,6 +1,7 @@
 import type { MigrationOptions } from '../../migrationOptions';
+import { isPgLiteral } from '../../utils';
 import type { Literal } from '../../utils/createTransformer';
-import type { Name } from '../generalTypes';
+import { isNameObject, isSchemaNameObject, type Name } from '../generalTypes';
 import type { CreateIndexOptions } from './createIndex';
 import type { DropIndexOptions } from './dropIndex';
 
@@ -12,24 +13,44 @@ export interface IndexColumn {
   sort?: 'ASC' | 'DESC';
 }
 
+function isIndexColumn(value: unknown): value is IndexColumn {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'name' in value &&
+    typeof (value as { name?: unknown }).name === 'string'
+  );
+}
+
 export function generateIndexName(
   table: Name,
   columns: Array<string | IndexColumn>,
   options: CreateIndexOptions | DropIndexOptions,
   schemalize: Literal
 ): Name {
   if (options.name) {
-    return typeof table === 'object'
+    return isSchemaNameObject(table)
       ? { schema: table.schema, name: options.name }
       : options.name;
   }
 
   const cols = columns
-    .map((col) => schemalize(typeof col === 'string' ? col : col.name))
+    .map((col, idx) => {
+      if (isIndexColumn(col)) return schemalize(col.name);
+
+      if (isPgLiteral(col)) {
+        const literalValue = 'value' in col ? col.value : String(col);
+        throw new Error(
+          `Index name must be provided when using PgLiteral columns (column #${idx + 1}: ${literalValue})`
+        );
+      }
+
+      return schemalize(col);
+    })
     .join('_');
   const uniq = 'unique' in options && options.unique ? '_unique' : '';
 
-  return typeof table === 'object'
+  return isNameObject(table)
     ? {
         schema: table.schema,
         name: `${table.name}_${cols}${uniq}_index`,
@@ -41,29 +62,39 @@ export function generateColumnString(
   column: Name,
   mOptions: MigrationOptions
 ): string {
+  if (isPgLiteral(column)) {
+    return column.toString();
+  }
+
   const name = mOptions.schemalize(column);
-  const isSpecial = /[ ().]/.test(name);
+  const isExpression = /[^\w".]/.test(name);
+  if (!isExpression) {
+    return mOptions.literal(name);
+  }
 
-  return isSpecial
-    ? name // expression
-    : mOptions.literal(name); // single column
+  // Expressions need parentheses in index definitions, unless they're already
+  // wrapped (we consider any expression ending with ')' as already wrapped).
+  const alreadyWrapped = /\)$/.test(name);
+  return alreadyWrapped ? name : `(${name})`;
 }
 
 export function generateColumnsString(
   columns: Array<string | IndexColumn>,
   mOptions: MigrationOptions
 ): string {
   return columns
-    .map((column) =>
-      typeof column === 'string'
-        ? generateColumnString(column, mOptions)
-        : [
-            generateColumnString(column.name, mOptions),
-            column.opclass ? mOptions.literal(column.opclass) : undefined,
-            column.sort,
-          ]
-            .filter((s) => typeof s === 'string' && s !== '')
-            .join(' ')
-    )
+    .map((column) => {
+      if (typeof column === 'string' || isPgLiteral(column)) {
+        return generateColumnString(column as unknown as Name, mOptions);
+      }
+
+      return [
+        generateColumnString(column.name, mOptions),
+        column.opclass ? mOptions.literal(column.opclass) : undefined,
+        column.sort,
+      ]
+        .filter((s) => typeof s === 'string' && s !== '')
+        .join(' ');
+    })
     .join(', ');
 }

src/operations/tables/shared.ts

@@ -3,6 +3,7 @@ import { applyType, escapeValue, makeComment, toArray } from '../../utils';
 import type { Literal } from '../../utils/createTransformer';
 import type { FunctionParamType } from '../functions';
 import type { IfNotExistsOption, Name, Value } from '../generalTypes';
+import { isNameObject } from '../generalTypes';
 import { parseSequenceOptions, type SequenceOptions } from '../sequences';
 
 export type Action =
@@ -330,7 +331,7 @@ export function parseConstraints(
     comment,
   }: ConstraintOptions = options;
 
-  const tableName = typeof table === 'object' ? table.name : table;
+  const tableName = isNameObject(table) ? table.name : table;
 
   let constraints: string[] = [];
   const comments: string[] = [];

src/utils/createSchemalize.ts

@@ -1,13 +1,53 @@
 import type { Name } from '../operations/generalTypes';
 import { decamelize } from './decamelize';
 import { identity } from './identity';
+import { isPgLiteral } from './PgLiteral';
 import { quote } from './quote';
 
 export interface SchemalizeOptions {
   readonly shouldDecamelize: boolean;
   readonly shouldQuote: boolean;
 }
 
+// Detect raw SQL expressions (used by indexes, constraints, etc.) to decide when to wrap in parentheses.
+//
+// Important: this is not a SQL sanitizer. It’s only a heuristic so that expression-based index columns like
+//   meta->>'type'
+//   meta#>>'{a,b}'
+//   lower(email)
+//   score * 10
+// are treated as expressions instead of quoted identifiers.
+//
+// JSON/JSONB operators reference:
+// https://www.postgresql.org/docs/current/functions-json.html
+//
+// Notes:
+// - We include single-char operators like '?' and '-' but only treat them as expression operators when
+//   there is at least one alphanumeric character in the string (handled by the final logical check).
+const OPERATOR_PATTERN = /(->>|->|#>>|#>|@\?|@@|@>|<@|\?\||\?&|\?|#-|\|\||::)/;
+const LOGICAL_PATTERN = /[=<>!]+/;
+const FUNCTION_CALL_PATTERN = /^[\w.]+\(/;
+const ARITHMETIC_PATTERN = /\s+[+*/-]\s+/;
+const ALPHANUMERIC_PATTERN = /[a-zA-Z0-9]/;
+
+function isExpression(value: string): boolean {
+  if (OPERATOR_PATTERN.test(value)) {
+    return true;
+  }
+
+  if (FUNCTION_CALL_PATTERN.test(value)) {
+    return true;
+  }
+
+  if (ARITHMETIC_PATTERN.test(value)) {
+    return true;
+  }
+
+  // Ensure we only treat strings with logical operators as expressions when they also contain alphanumeric characters.
+  // This avoids false positives from standalone operators like ">" or "!=".
+  return LOGICAL_PATTERN.test(value) && ALPHANUMERIC_PATTERN.test(value);
+}
+
 export function createSchemalize(
   options: SchemalizeOptions
 ): (value: Name) => string {
@@ -18,12 +58,29 @@ export function createSchemalize(
     shouldQuote ? quote : identity,
   ].reduce((acc, fn) => (fn === identity ? acc : (str) => acc(fn(str))));
 
-  return (value) => {
-    if (typeof value === 'object') {
+  return (value: Name) => {
+    if (isPgLiteral(value)) {
+      return value.toString();
+    }
+
+    if (typeof value === 'object' && value !== null) {
       const { schema, name } = value;
-      return (schema ? `${transform(schema)}.` : '') + transform(name);
+
+      if (name !== undefined) {
+        return (schema ? `${transform(schema)}.` : '') + transform(name);
+      }
+    }
+
+    // Wrap raw SQL expressions in parentheses only when not quoting;
+    // quoted values are treated as identifiers/literals and must stay unchanged.
+    if (!shouldQuote && typeof value === 'string' && isExpression(value)) {
+      return `(${value})`;
+    }
+
+    if (typeof value === 'string') {
+      return transform(value);
     }
 
-    return transform(value);
+    return transform(String(value));
   };
 }

src/utils/createTransformer.ts

@@ -1,5 +1,9 @@
 import { escapeValue } from '.';
-import type { Name, Value } from '../operations/generalTypes';
+import {
+  isNameObject,
+  type Name,
+  type Value,
+} from '../operations/generalTypes';
 
 export type Literal = (v: Name) => string;
 
@@ -13,8 +17,7 @@ export function createTransformer(
         new RegExp(`{${param}}`, 'g'),
         val === undefined
           ? ''
-          : typeof val === 'string' ||
-              (typeof val === 'object' && val !== null && 'name' in val)
+          : typeof val === 'string' || isNameObject(val)
             ? literal(val)
             : String(escapeValue(val)).replace(/\$/g, '$$$$')
       );

src/utils/quote.ts

@@ -1,3 +1,12 @@
+/**
+ * Quote an identifier for PostgreSQL.
+ *
+ * Wraps the given string in double quotes and escapes any embedded double
+ * quotes by doubling them, per PostgreSQL identifier rules.
+ *
+ * @param str - identifier to quote
+ * @returns quoted identifier safe for use as a PostgreSQL identifier
+ */
 export function quote(str: string): string {
-  return `"${str}"`;
+  return `"${str.replace(/"/g, '""')}"`;
 }

test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-13.stdout.log

@@ -1,4 +1,5 @@
 > Migrating files:
+> - 096_expression_index
 > - 095_index_nulls
 > - 094_unlogged_table
 > - 093_alter_column_expression
@@ -94,6 +95,25 @@
 > - 003_promise
 > - 002_callback
 > - 001_noop
+### MIGRATION 096_expression_index (DOWN) ###
+DROP INDEX "pgm_users_meta_id_json_operator_idx";
+DROP INDEX "pgm_users_meta_id_text_operator_idx";
+DROP INDEX "pgm_users_meta_path_json_operator_idx";
+DROP INDEX "pgm_users_meta_path_text_operator_idx";
+DROP INDEX "pgm_users_meta_contains_operator_idx";
+DROP INDEX "pgm_users_meta_contained_operator_idx";
+DROP INDEX "pgm_users_meta_has_key_operator_idx";
+DROP INDEX "pgm_users_meta_has_any_operator_idx";
+DROP INDEX "pgm_users_meta_has_all_operator_idx";
+DROP INDEX "pgm_users_meta_concat_operator_idx";
+DROP INDEX "pgm_users_meta_remove_key_operator_idx";
+DROP INDEX "pgm_users_meta_remove_path_operator_idx";
+DROP INDEX "pgm_users_meta_path_exists_operator_idx";
+DROP INDEX "pgm_users_meta_path_predicate_operator_idx";
+DROP TABLE "pgm_users";
+DELETE FROM "public"."pgmigrations" WHERE name='096_expression_index';
+
+
 ### MIGRATION 095_index_nulls (DOWN) ###
 DELETE FROM "public"."pgmigrations" WHERE name='095_index_nulls';
 

test/integration/__snapshots__/db-config-it.spec.ts.snap.d/migrations-down.pg-14.stdout.log

@@ -1,4 +1,5 @@
 > Migrating files:
+> - 096_expression_index
 > - 095_index_nulls
 > - 094_unlogged_table
 > - 093_alter_column_expression
@@ -94,6 +95,25 @@
 > - 003_promise
 > - 002_callback
 > - 001_noop
+### MIGRATION 096_expression_index (DOWN) ###
+DROP INDEX "pgm_users_meta_id_json_operator_idx";
+DROP INDEX "pgm_users_meta_id_text_operator_idx";
+DROP INDEX "pgm_users_meta_path_json_operator_idx";
+DROP INDEX "pgm_users_meta_path_text_operator_idx";
+DROP INDEX "pgm_users_meta_contains_operator_idx";
+DROP INDEX "pgm_users_meta_contained_operator_idx";
+DROP INDEX "pgm_users_meta_has_key_operator_idx";
+DROP INDEX "pgm_users_meta_has_any_operator_idx";
+DROP INDEX "pgm_users_meta_has_all_operator_idx";
+DROP INDEX "pgm_users_meta_concat_operator_idx";
+DROP INDEX "pgm_users_meta_remove_key_operator_idx";
+DROP INDEX "pgm_users_meta_remove_path_operator_idx";
+DROP INDEX "pgm_users_meta_path_exists_operator_idx";
+DROP INDEX "pgm_users_meta_path_predicate_operator_idx";
+DROP TABLE "pgm_users";
+DELETE FROM "public"."pgmigrations" WHERE name='096_expression_index';
+
+
 ### MIGRATION 095_index_nulls (DOWN) ###
 DELETE FROM "public"."pgmigrations" WHERE name='095_index_nulls';