@housekit/orm 0.1.26 → 0.1.27

package/README.md

@@ -178,15 +178,22 @@ await db.insert(events).values([
 
 ### JSON Insert with Returning
 
-Use `.returning()` when you need the inserted data back:
+Use `.returningOne()` for single inserts or `.returning()` for multiple:
 
 ```typescript
-const [user] = await db
+// Single insert
+const user = await db
   .insert(users)
   .values({ email: 'a@b.com', role: 'admin' })
-  .returning();
+  .returningOne();
 
 console.log(user.id); // Generated UUID
+
+// Multiple inserts
+const [user1, user2] = await db
+  .insert(users)
+  .values([{ email: 'a@b.com' }, { email: 'b@c.com' }])
+  .returning();
 ```
 
 ### Force JSON Format

package/dist/builders/insert.d.ts

@@ -34,7 +34,19 @@ export declare class ClickHouseInsertBuilder<TTable extends TableRuntime<any, an
     values(value: CleanInsert<TTable> | Array<CleanInsert<TTable>> | Iterable<CleanInsert<TTable>> | AsyncIterable<CleanInsert<TTable>> | Readable): ClickHouseInsertBuilder<TTable, TReturn>;
     /** @template [T = CleanInsert<TTable>] */
     insert(data: CleanInsert<TTable> | CleanInsert<TTable>[]): Promise<TReturn>;
+    /**
+     * Return inserted data as an array.
+     * Use when inserting multiple rows.
+     */
     returning(): ClickHouseInsertBuilder<TTable, CleanSelect<TTable>[]>;
+    /**
+     * Return the single inserted row directly (not wrapped in array).
+     * Use when inserting a single value for cleaner syntax.
+     *
+     * @example
+     * const user = await db.insert(users).values({ email: 'a@b.com' }).returningOne();
+     */
+    returningOne(): ClickHouseInsertBuilder<TTable, CleanSelect<TTable>>;
     /**
      * Disable the default returning() behavior.
      * Useful when you don't need the inserted data back and want to avoid the overhead.

package/dist/index.js

@@ -4707,6 +4707,11 @@ class ClickHouseInsertBuilder {
     this._returning = true;
     return this;
   }
+  returningOne() {
+    this._returning = true;
+    this._isSingle = true;
+    return this;
+  }
   noReturning() {
     this._returning = false;
     return this;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@housekit/orm",
-    "version": "0.1.26",
+    "version": "0.1.27",
     "description": "Type-safe ClickHouse ORM with modern DX and ClickHouse-specific optimizations. Features Turbo Mode (RowBinary), full engine support, and advanced query capabilities.",
     "type": "module",
     "main": "./dist/index.js",