sqlite-zod-orm 3.13.0 → 3.15.0

package/dist/index.js

@@ -4042,6 +4042,8 @@ function zodTypeToSqlType(zodType) {
     return "TEXT";
   if (zodType instanceof exports_external.ZodNumber || zodType instanceof exports_external.ZodBoolean)
     return "INTEGER";
+  if (zodType instanceof exports_external.ZodEnum)
+    return "TEXT";
   if (zodType._def.typeName === "ZodInstanceOf" && zodType._def.type === Buffer)
     return "BLOB";
   return "TEXT";
@@ -4053,6 +4055,8 @@ function transformForStorage(data) {
       transformed[key] = value.toISOString();
     } else if (typeof value === "boolean") {
       transformed[key] = value ? 1 : 0;
+    } else if (value !== null && value !== undefined && typeof value === "object" && !(value instanceof Buffer)) {
+      transformed[key] = JSON.stringify(value);
     } else {
       transformed[key] = value;
     }
@@ -4073,12 +4077,23 @@ function transformFromStorage(row, schema) {
       transformed[key] = new Date(value);
     } else if (fieldSchema instanceof exports_external.ZodBoolean && typeof value === "number") {
       transformed[key] = value === 1;
+    } else if (isJsonSchema(fieldSchema) && typeof value === "string") {
+      try {
+        transformed[key] = JSON.parse(value);
+      } catch {
+        transformed[key] = value;
+      }
     } else {
       transformed[key] = value;
     }
   }
   return transformed;
 }
+function isJsonSchema(schema) {
+  if (!schema)
+    return false;
+  return schema instanceof exports_external.ZodObject || schema instanceof exports_external.ZodArray || schema instanceof exports_external.ZodRecord || schema instanceof exports_external.ZodTuple || schema instanceof exports_external.ZodUnion || schema instanceof exports_external.ZodDiscriminatedUnion;
+}
 
 // src/ast.ts
 var wrapNode = (val) => val !== null && typeof val === "object" && ("type" in val) ? val : { type: "literal", value: val };
@@ -4244,6 +4259,12 @@ function compileIQO(tableName, iqo) {
       }
     }
   }
+  if (iqo.rawWheres && iqo.rawWheres.length > 0) {
+    for (const rw of iqo.rawWheres) {
+      sql += sql.includes(" WHERE ") ? ` AND (${rw.sql})` : ` WHERE (${rw.sql})`;
+      params.push(...rw.params);
+    }
+  }
   if (iqo.groupBy.length > 0) {
     sql += ` GROUP BY ${iqo.groupBy.join(", ")}`;
   }
@@ -4293,6 +4314,7 @@ class QueryBuilder {
       selects: [],
       wheres: [],
       whereOrs: [],
+      rawWheres: [],
       whereAST: null,
       joins: [],
       groupBy: [],
@@ -4403,6 +4425,10 @@ class QueryBuilder {
     this.iqo.raw = true;
     return this;
   }
+  whereRaw(sql, params = []) {
+    this.iqo.rawWheres.push({ sql, params });
+    return this;
+  }
   with(...relations) {
     this.iqo.includes.push(...relations);
     return this;
@@ -5001,6 +5027,14 @@ function upsert(ctx, entityName, data, conditions = {}) {
   delete insertData.id;
   return insert(ctx, entityName, insertData);
 }
+function findOrCreate(ctx, entityName, conditions, defaults = {}) {
+  const existing = getOne(ctx, entityName, conditions);
+  if (existing)
+    return { entity: existing, created: false };
+  const data = { ...conditions, ...defaults };
+  delete data.id;
+  return { entity: insert(ctx, entityName, data), created: true };
+}
 function deleteEntity(ctx, entityName, id) {
   const hooks = ctx.hooks[entityName];
   if (hooks?.beforeDelete) {
@@ -5184,6 +5218,7 @@ class _Database {
         },
         upsert: (conditions, data) => upsert(this._ctx, entityName, data, conditions),
         upsertMany: (rows, conditions) => upsertMany(this._ctx, entityName, rows, conditions),
+        findOrCreate: (conditions, defaults) => findOrCreate(this._ctx, entityName, conditions, defaults),
         delete: (id) => {
           if (typeof id === "number") {
             const hooks = this._ctx.hooks[entityName];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlite-zod-orm",
-  "version": "3.13.0",
+  "version": "3.15.0",
   "description": "Type-safe SQLite ORM for Bun — Zod schemas, fluent queries, auto relationships, zero SQL",
   "type": "module",
   "main": "./dist/index.js",

package/src/builder.ts

@@ -27,7 +27,7 @@ import {
  * - Object-style: `.where({ name: 'Alice', age: { $gt: 18 } })`
  * - Callback-style (AST): `.where((c, f, op) => op.and(op.eq(c.name, 'Alice'), op.gt(c.age, 18)))`
  */
-export class QueryBuilder<T extends Record<string, any>> {
+export class QueryBuilder<T extends Record<string, any>, TResult extends Record<string, any> = T> {
     private iqo: IQO;
     private tableName: string;
     private executor: (sql: string, params: any[], raw: boolean) => any[];
@@ -54,6 +54,7 @@ export class QueryBuilder<T extends Record<string, any>> {
             selects: [],
             wheres: [],
             whereOrs: [],
+            rawWheres: [],
             whereAST: null,
             joins: [],
             groupBy: [],
@@ -68,7 +69,9 @@ export class QueryBuilder<T extends Record<string, any>> {
     }
 
     /** Specify which columns to select. If called with no arguments, defaults to `*`. */
-    select(...cols: (keyof T & string)[]): this {
+    select(): this;
+    select<K extends keyof T & string>(...cols: K[]): QueryBuilder<T, Pick<T, K>>;
+    select(...cols: string[]): any {
         this.iqo.selects.push(...cols);
         return this;
     }
@@ -215,6 +218,19 @@ export class QueryBuilder<T extends Record<string, any>> {
         return this;
     }
 
+    /**
+     * Add a raw SQL WHERE fragment with parameterized values.
+     * Can be combined with `.where()` — fragments are AND'd together.
+     *
+     * ```ts
+     * db.users.select().whereRaw('score > ? AND role != ?', [50, 'guest']).all()
+     * ```
+     */
+    whereRaw(sql: string, params: any[] = []): this {
+        this.iqo.rawWheres.push({ sql, params });
+        return this;
+    }
+
     /**
      * Eagerly load a related entity and attach as an array property.
      *
@@ -250,20 +266,20 @@ export class QueryBuilder<T extends Record<string, any>> {
     // ---------- Terminal / Execution Methods ----------
 
     /** Execute the query and return all matching rows. */
-    all(): T[] {
+    all(): TResult[] {
         const { sql, params } = compileIQO(this.tableName, this.iqo);
         const results = this.executor(sql, params, this.iqo.raw);
-        return this._applyEagerLoads(results);
+        return this._applyEagerLoads(results) as unknown as TResult[];
     }
 
     /** Execute the query and return the first matching row, or null. */
-    get(): T | null {
+    get(): TResult | null {
         this.iqo.limit = 1;
         const { sql, params } = compileIQO(this.tableName, this.iqo);
         const result = this.singleExecutor(sql, params, this.iqo.raw);
         if (!result) return null;
         const [loaded] = this._applyEagerLoads([result]);
-        return loaded ?? null;
+        return (loaded ?? null) as TResult | null;
     }
 
     /** Execute the query and return the count of matching rows. */
@@ -277,7 +293,7 @@ export class QueryBuilder<T extends Record<string, any>> {
     }
 
     /** Alias for get() — returns the first matching row or null. */
-    first(): T | null {
+    first(): TResult | null {
         return this.get();
     }
 
@@ -385,7 +401,7 @@ export class QueryBuilder<T extends Record<string, any>> {
     }
 
     /** Paginate results. Returns { data, total, page, perPage, pages }. */
-    paginate(page: number = 1, perPage: number = 20): { data: T[]; total: number; page: number; perPage: number; pages: number } {
+    paginate(page: number = 1, perPage: number = 20): { data: TResult[]; total: number; page: number; perPage: number; pages: number } {
         const total = this.count();
         const pages = Math.ceil(total / perPage);
         this.iqo.limit = perPage;
@@ -420,10 +436,10 @@ export class QueryBuilder<T extends Record<string, any>> {
 
     // ---------- Thenable (async/await support) ----------
 
-    then<TResult1 = T[], TResult2 = never>(
-        onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null,
-        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
-    ): Promise<TResult1 | TResult2> {
+    then<TThen1 = TResult[], TThen2 = never>(
+        onfulfilled?: ((value: TResult[]) => TThen1 | PromiseLike<TThen1>) | null,
+        onrejected?: ((reason: any) => TThen2 | PromiseLike<TThen2>) | null,
+    ): Promise<TThen1 | TThen2> {
         try {
             const result = this.all();
             return Promise.resolve(result).then(onfulfilled, onrejected);

package/src/crud.ts

@@ -156,6 +156,19 @@ export function upsert<T extends Record<string, any>>(ctx: DatabaseContext, enti
     return insert(ctx, entityName, insertData);
 }
 
+/** Find a row matching conditions, or create it with the merged data. Returns { entity, created }. */
+export function findOrCreate<T extends Record<string, any>>(
+    ctx: DatabaseContext, entityName: string,
+    conditions: Record<string, any>,
+    defaults: Record<string, any> = {},
+): { entity: AugmentedEntity<any>; created: boolean } {
+    const existing = getOne(ctx, entityName, conditions);
+    if (existing) return { entity: existing, created: false };
+    const data = { ...conditions, ...defaults };
+    delete (data as any).id;
+    return { entity: insert(ctx, entityName, data), created: true };
+}
+
 export function deleteEntity(ctx: DatabaseContext, entityName: string, id: number): void {
     // beforeDelete hook — return false to cancel
     const hooks = ctx.hooks[entityName];

package/src/database.ts

@@ -24,7 +24,7 @@ import type { DatabaseContext } from './context';
 import { buildWhereClause } from './helpers';
 import { attachMethods } from './entity';
 import {
-    insert, insertMany, update, upsert, upsertMany, deleteEntity, createDeleteBuilder,
+    insert, insertMany, update, upsert, upsertMany, findOrCreate, deleteEntity, createDeleteBuilder,
     getById, getOne, findMany, updateWhere, createUpdateBuilder,
 } from './crud';
 
@@ -107,6 +107,7 @@ class _Database<Schemas extends SchemaMap> {
                 },
                 upsert: (conditions, data) => upsert(this._ctx, entityName, data, conditions),
                 upsertMany: (rows: any[], conditions?: any) => upsertMany(this._ctx, entityName, rows, conditions),
+                findOrCreate: (conditions: any, defaults?: any) => findOrCreate(this._ctx, entityName, conditions, defaults),
                 delete: ((id?: any) => {
                     if (typeof id === 'number') {
                         // beforeDelete hook — return false to cancel

package/src/iqo.ts

@@ -31,6 +31,7 @@ export interface IQO {
     selects: string[];
     wheres: WhereCondition[];
     whereOrs: WhereCondition[][];  // Each sub-array is an OR group
+    rawWheres: { sql: string; params: any[] }[];  // Raw WHERE fragments
     whereAST: ASTNode | null;
     joins: JoinClause[];
     groupBy: string[];
@@ -162,6 +163,14 @@ export function compileIQO(tableName: string, iqo: IQO): { sql: string; params:
         }
     }
 
+    // Append raw WHERE fragments
+    if (iqo.rawWheres && iqo.rawWheres.length > 0) {
+        for (const rw of iqo.rawWheres) {
+            sql += sql.includes(' WHERE ') ? ` AND (${rw.sql})` : ` WHERE (${rw.sql})`;
+            params.push(...rw.params);
+        }
+    }
+
     // GROUP BY
     if (iqo.groupBy.length > 0) {
         sql += ` GROUP BY ${iqo.groupBy.join(', ')}`;

package/src/schema.ts

@@ -80,7 +80,9 @@ export function zodTypeToSqlType(zodType: ZodType): string {
     }
     if (zodType instanceof z.ZodString || zodType instanceof z.ZodDate) return 'TEXT';
     if (zodType instanceof z.ZodNumber || zodType instanceof z.ZodBoolean) return 'INTEGER';
+    if (zodType instanceof z.ZodEnum) return 'TEXT';
     if ((zodType as any)._def.typeName === 'ZodInstanceOf' && (zodType as any)._def.type === Buffer) return 'BLOB';
+    // z.object(), z.array(), z.record() → stored as JSON TEXT
     return 'TEXT';
 }
 
@@ -92,6 +94,9 @@ export function transformForStorage(data: Record<string, any>): Record<string, a
             transformed[key] = value.toISOString();
         } else if (typeof value === 'boolean') {
             transformed[key] = value ? 1 : 0;
+        } else if (value !== null && value !== undefined && typeof value === 'object' && !(value instanceof Buffer)) {
+            // Auto-serialize objects and arrays to JSON
+            transformed[key] = JSON.stringify(value);
         } else {
             transformed[key] = value;
         }
@@ -114,9 +119,25 @@ export function transformFromStorage(row: Record<string, any>, schema: z.ZodType
             transformed[key] = new Date(value);
         } else if (fieldSchema instanceof z.ZodBoolean && typeof value === 'number') {
             transformed[key] = value === 1;
+        } else if (isJsonSchema(fieldSchema) && typeof value === 'string') {
+            // Auto-parse JSON columns
+            try { transformed[key] = JSON.parse(value); } catch { transformed[key] = value; }
         } else {
             transformed[key] = value;
         }
     }
     return transformed;
 }
+
+/** Check if a Zod schema represents a JSON-serializable type */
+function isJsonSchema(schema: any): boolean {
+    if (!schema) return false;
+    return (
+        schema instanceof z.ZodObject ||
+        schema instanceof z.ZodArray ||
+        schema instanceof z.ZodRecord ||
+        schema instanceof z.ZodTuple ||
+        schema instanceof z.ZodUnion ||
+        schema instanceof z.ZodDiscriminatedUnion
+    );
+}

package/src/types.ts

@@ -206,9 +206,13 @@ export type NavEntityAccessor<
     & ((data: Partial<Omit<z.input<S[Table & keyof S]>, 'id'>>) => UpdateBuilder<NavEntity<S, R, Table>>);
     upsert: (conditions?: Partial<z.infer<S[Table & keyof S]>>, data?: Partial<z.infer<S[Table & keyof S]>>) => NavEntity<S, R, Table>;
     upsertMany: (rows: Partial<z.infer<S[Table & keyof S]>>[], conditions?: Partial<z.infer<S[Table & keyof S]>>) => NavEntity<S, R, Table>[];
+    findOrCreate: (conditions: Partial<z.infer<S[Table & keyof S]>>, defaults?: Partial<z.infer<S[Table & keyof S]>>) => { entity: NavEntity<S, R, Table>; created: boolean };
     delete: ((id: number) => void) & (() => DeleteBuilder<NavEntity<S, R, Table>>);
     restore: (id: number) => void;
-    select: (...cols: (keyof z.infer<S[Table & keyof S]> & string)[]) => QueryBuilder<NavEntity<S, R, Table>>;
+    select: {
+        (): QueryBuilder<NavEntity<S, R, Table>>;
+        <K extends (keyof z.infer<S[Table & keyof S]> | 'id') & string>(...cols: K[]): QueryBuilder<NavEntity<S, R, Table>, Pick<NavEntity<S, R, Table>, K>>;
+    };
     on: ((event: 'insert' | 'update', callback: (row: NavEntity<S, R, Table>) => void | Promise<void>) => () => void) &
     ((event: 'delete', callback: (row: { id: number }) => void | Promise<void>) => () => void);
     _tableName: string;
@@ -238,10 +242,14 @@ export type EntityAccessor<S extends z.ZodType<any>> = {
     update: ((id: number, data: Partial<EntityData<S>>) => AugmentedEntity<S> | null) & ((data: Partial<EntityData<S>>) => UpdateBuilder<AugmentedEntity<S>>);
     upsert: (conditions?: Partial<InferSchema<S>>, data?: Partial<InferSchema<S>>) => AugmentedEntity<S>;
     upsertMany: (rows: Partial<InferSchema<S>>[], conditions?: Partial<InferSchema<S>>) => AugmentedEntity<S>[];
+    findOrCreate: (conditions: Partial<InferSchema<S>>, defaults?: Partial<InferSchema<S>>) => { entity: AugmentedEntity<S>; created: boolean };
     delete: ((id: number) => void) & (() => DeleteBuilder<AugmentedEntity<S>>);
     /** Undo a soft delete by setting deletedAt = null. Requires softDeletes. */
     restore: (id: number) => void;
-    select: (...cols: (keyof InferSchema<S> & string)[]) => QueryBuilder<AugmentedEntity<S>>;
+    select: {
+        (): QueryBuilder<AugmentedEntity<S>>;
+        <K extends (keyof InferSchema<S> | 'id') & string>(...cols: K[]): QueryBuilder<AugmentedEntity<S>, Pick<AugmentedEntity<S>, K>>;
+    };
     on: ((event: 'insert' | 'update', callback: (row: AugmentedEntity<S>) => void | Promise<void>) => () => void) &
     ((event: 'delete', callback: (row: { id: number }) => void | Promise<void>) => () => void);
     _tableName: string;