feat: add string matching methods (whereLike, whereStartsWith, whereEndsWith) to QueryBuilder and Relation classes; update Kysely adapter to support raw where clauses

Author: 3m1n3nc3

package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkormx",
-  "version": "2.0.0-next.21",
+  "version": "2.0.0-next.22",
   "description": "Modern TypeScript-first ORM for Node.js.",
   "keywords": [
     "orm",

src/QueryBuilder.ts

@@ -289,6 +289,48 @@ export class QueryBuilder<TModel, TDelegate extends PrismaDelegateLike = PrismaD
         return this.where({ [key]: { notIn: values } } as DelegateWhere<TDelegate>)
     }
 
+    /**
+     * Adds a string contains clause for a single attribute key.
+     *
+     * @param key
+     * @param value
+     * @returns
+     */
+    public whereLike<TKey extends keyof ModelAttributes<TModel> & string> (
+        key: TKey,
+        value: Extract<ModelAttributes<TModel>[TKey], string>
+    ): this {
+        return this.where({ [key]: { contains: value } } as DelegateWhere<TDelegate>)
+    }
+
+    /**
+     * Adds a string starts-with clause for a single attribute key.
+     *
+     * @param key
+     * @param value
+     * @returns
+     */
+    public whereStartsWith<TKey extends keyof ModelAttributes<TModel> & string> (
+        key: TKey,
+        value: Extract<ModelAttributes<TModel>[TKey], string>
+    ): this {
+        return this.where({ [key]: { startsWith: value } } as DelegateWhere<TDelegate>)
+    }
+
+    /**
+     * Adds a string ends-with clause for a single attribute key.
+     *
+     * @param key
+     * @param value
+     * @returns
+     */
+    public whereEndsWith<TKey extends keyof ModelAttributes<TModel> & string> (
+        key: TKey,
+        value: Extract<ModelAttributes<TModel>[TKey], string>
+    ): this {
+        return this.where({ [key]: { endsWith: value } } as DelegateWhere<TDelegate>)
+    }
+
     /**
      * Adds a strongly-typed OR NOT IN where clause for a single attribute key.
      *

src/adapters/KyselyDatabaseAdapter.ts

@@ -75,7 +75,7 @@ export class KyselyDatabaseAdapter implements DatabaseAdapter {
         relationLoads: false,
         relationAggregates: true,
         relationFilters: true,
-        rawWhere: false,
+        rawWhere: true,
     }
 
     public constructor(
@@ -578,6 +578,30 @@ export class KyselyDatabaseAdapter implements DatabaseAdapter {
         return sql<boolean>`${column} ${operator} ${condition.value}`
     }
 
+    private buildRawWhereCondition (condition: QueryRawCondition): RawBuilder<boolean> {
+        const segments = condition.sql.split('?')
+        const bindings = condition.bindings ?? []
+
+        if (segments.length !== bindings.length + 1) {
+            throw new ArkormException('Raw where bindings do not match the number of placeholders.')
+        }
+
+        const parts: RawBuilder<unknown>[] = []
+
+        segments.forEach((segment, index) => {
+            if (segment.length > 0)
+                parts.push(sql.raw(segment))
+
+            if (index < bindings.length)
+                parts.push(sql`${bindings[index]}`)
+        })
+
+        if (parts.length === 0)
+            return sql<boolean>`1 = 1`
+
+        return sql<boolean>`${sql.join(parts, sql``)}`
+    }
+
     private buildWhereCondition (target: QueryTarget<any>, condition?: QueryCondition): RawBuilder<boolean> {
         if (!condition)
             return sql<boolean>`1 = 1`
@@ -607,13 +631,7 @@ export class KyselyDatabaseAdapter implements DatabaseAdapter {
             return sql<boolean>`not (${this.buildWhereCondition(target, notCondition.condition)})`
         }
 
-        throw new UnsupportedAdapterFeatureException('Raw where clauses are not supported by the Kysely adapter.', {
-            operation: 'adapter.where',
-            meta: {
-                feature: 'rawWhere',
-                sql: (condition as QueryRawCondition).sql,
-            },
-        })
+        return this.buildRawWhereCondition(condition as QueryRawCondition)
     }
 
     private buildWhereClause (target: QueryTarget<any>, condition?: QueryCondition): RawBuilder<unknown> {

src/relationship/Relation.ts

@@ -99,6 +99,48 @@ export abstract class Relation<TModel> {
         return this.constrain(query => query.whereIn(key, values))
     }
 
+    /**
+     * Add a string contains clause to the relationship query.
+     *
+     * @param key
+     * @param value
+     * @returns
+     */
+    public whereLike<TKey extends keyof ModelAttributes<TModel> & string> (
+        key: TKey,
+        value: Extract<ModelAttributes<TModel>[TKey], string>
+    ): this {
+        return this.constrain(query => query.whereLike(key, value))
+    }
+
+    /**
+     * Add a string starts-with clause to the relationship query.
+     *
+     * @param key
+     * @param value
+     * @returns
+     */
+    public whereStartsWith<TKey extends keyof ModelAttributes<TModel> & string> (
+        key: TKey,
+        value: Extract<ModelAttributes<TModel>[TKey], string>
+    ): this {
+        return this.constrain(query => query.whereStartsWith(key, value))
+    }
+
+    /**
+     * Add a string ends-with clause to the relationship query.
+     *
+     * @param key
+     * @param value
+     * @returns
+     */
+    public whereEndsWith<TKey extends keyof ModelAttributes<TModel> & string> (
+        key: TKey,
+        value: Extract<ModelAttributes<TModel>[TKey], string>
+    ): this {
+        return this.constrain(query => query.whereEndsWith(key, value))
+    }
+
     /**
      * Add an order by clause to the relationship query.
      *

tests/base/helpers/core-fixtures.ts

@@ -96,6 +96,24 @@ function matchesWhere (row: Row, where: Record<string, unknown> | undefined): bo
                     return false
             }
 
+            if ('contains' in clause) {
+                const candidate = clause.contains
+                if (typeof rowValue !== 'string' || typeof candidate !== 'string' || !rowValue.includes(candidate))
+                    return false
+            }
+
+            if ('startsWith' in clause) {
+                const candidate = clause.startsWith
+                if (typeof rowValue !== 'string' || typeof candidate !== 'string' || !rowValue.startsWith(candidate))
+                    return false
+            }
+
+            if ('endsWith' in clause) {
+                const candidate = clause.endsWith
+                if (typeof rowValue !== 'string' || typeof candidate !== 'string' || !rowValue.endsWith(candidate))
+                    return false
+            }
+
             if ('gt' in clause) {
                 const compareTo = clause.gt
                 const leftValue = toComparable(rowValue, compareTo)

tests/base/query-builder.spec.ts

@@ -469,6 +469,15 @@ describe('QueryBuilder', () => {
         const orWhereNotIn = await User.query().whereKey('id', 1).orWhereNotIn('id', [1]).orderBy({ id: 'asc' }).get()
         expect(orWhereNotIn.all().map(user => user.getAttribute('id'))).toEqual([1, 2])
 
+        const whereLike = await User.query().whereLike('email', '@example.com').orderBy({ id: 'asc' }).get()
+        expect(whereLike.all().map(user => user.getAttribute('id'))).toEqual([1, 2])
+
+        const whereStartsWith = await User.query().whereStartsWith('email', 'jane').get()
+        expect(whereStartsWith.all().map(user => user.getAttribute('id'))).toEqual([1])
+
+        const whereEndsWith = await User.query().whereEndsWith('email', '@example.com').orderBy({ id: 'asc' }).get()
+        expect(whereEndsWith.all().map(user => user.getAttribute('id'))).toEqual([1, 2])
+
         const whereDate = await User.query().whereDate('createdAt', '2026-03-04').get()
         expect(whereDate.all().length).toBe(2)
 

tests/base/relationships.spec.ts

@@ -272,16 +272,28 @@ describe('Model relationships', () => {
         expect(user).not.toBeNull()
 
         const posts = await user?.posts()
-            .where({ title: 'A' })
+            .whereStartsWith('title', 'A')
             .orderBy({ id: 'asc' })
             .getResults()
 
         const profile = await user?.profile()
             .where({ id: 10 })
             .getResults()
 
+        const postsEndingWithB = await user?.posts()
+            .whereEndsWith('title', 'B')
+            .getResults()
+
+        const postsLike = await user?.posts()
+            .whereLike('title', 'A')
+            .getResults()
+
         expect((posts as ArkormCollection<Post>).all().length).toBe(1)
         expect((posts as ArkormCollection<Post>).all()[0]?.getAttribute('title')).toBe('A')
+        expect((postsEndingWithB as ArkormCollection<Post>).all().length).toBe(1)
+        expect((postsEndingWithB as ArkormCollection<Post>).all()[0]?.getAttribute('title')).toBe('B')
+        expect((postsLike as ArkormCollection<Post>).all().length).toBe(1)
+        expect((postsLike as ArkormCollection<Post>).all()[0]?.getAttribute('title')).toBe('A')
         expect(profile).not.toBeNull()
         expect((profile as Profile).getAttribute('id')).toBe(10)
     })

tests/postgres/kysely-adapter.spec.ts

@@ -204,6 +204,23 @@ describe('PostgreSQL Kysely adapter', () => {
         expect(trashedArticles.all().map(article => article.getAttribute('title'))).toEqual(['Archived'])
     })
 
+    it('supports raw where clauses through the Kysely adapter', async () => {
+        setPostgresModelAdapter(kyselyAdapter)
+
+        const normalizedLocalPart = 'jane'
+        const query = DbUser.query().whereRaw(
+            'LOWER("email") = ? OR LOWER("email") LIKE ?',
+            [`${normalizedLocalPart}@example.com`, `%${normalizedLocalPart}@%`],
+        )
+
+        const users = await query.get()
+
+        expect(users.all().map(user => user.getAttribute('email'))).toEqual(['[email protected]'])
+
+        const normalizedSql = executedQueries.join('\n').replace(/\s+/g, ' ')
+        expect(normalizedSql).toContain('LOWER("email") = $1 OR LOWER("email") LIKE $2')
+    })
+
     it('supports SQL-backed direct relation filters and aggregates through QueryBuilder', async () => {
         setPostgresModelAdapter(kyselyAdapter)