@leonardovida-md/drizzle-neo-duckdb 1.0.1 → 1.0.3

package/README.md

@@ -7,7 +7,7 @@
 [![npm version](https://img.shields.io/npm/v/@leonardovida-md/drizzle-neo-duckdb)](https://www.npmjs.com/package/@leonardovida-md/drizzle-neo-duckdb)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-[Documentation](./docs) • [Examples](./example) • [Contributing](#contributing)
+[Documentation](https://leonardovida-md.github.io/drizzle-neo-duckdb/) • [Examples](./example) • [Contributing](#contributing)
 
 </div>
 
@@ -119,7 +119,14 @@ Drizzle DuckDB uses `drizzle-orm/pg-core` for schema definitions since DuckDB's
 
 ```typescript
 import { sql } from 'drizzle-orm';
-import { integer, text, boolean, timestamp, pgTable, pgSchema } from 'drizzle-orm/pg-core';
+import {
+  integer,
+  text,
+  boolean,
+  timestamp,
+  pgTable,
+  pgSchema,
+} from 'drizzle-orm/pg-core';
 
 // Tables in default schema
 const posts = pgTable('posts', {
@@ -181,7 +188,7 @@ const products = pgTable('products', {
 });
 ```
 
-See [Column Types Documentation](./docs/columns.md) for complete reference.
+See [Column Types Documentation](https://leonardovida-md.github.io/drizzle-neo-duckdb/api/columns) for complete reference.
 
 ## Querying
 
@@ -189,10 +196,15 @@ All standard Drizzle query methods work:
 
 ```typescript
 // Select
-const users = await db.select().from(usersTable).where(eq(usersTable.active, true));
+const users = await db
+  .select()
+  .from(usersTable)
+  .where(eq(usersTable.active, true));
 
 // Insert
-await db.insert(usersTable).values({ name: 'Alice', email: 'alice@example.com' });
+await db
+  .insert(usersTable)
+  .values({ name: 'Alice', email: 'alice@example.com' });
 
 // Insert with returning
 const inserted = await db
@@ -201,7 +213,10 @@ const inserted = await db
   .returning({ id: usersTable.id });
 
 // Update
-await db.update(usersTable).set({ name: 'Updated' }).where(eq(usersTable.id, 1));
+await db
+  .update(usersTable)
+  .set({ name: 'Updated' })
+  .where(eq(usersTable.id, 1));
 
 // Delete
 await db.delete(usersTable).where(eq(usersTable.id, 1));
@@ -228,7 +243,9 @@ const results = await db
 const results = await db
   .select()
   .from(products)
-  .where(duckDbArrayContained(products.tags, ['electronics', 'sale', 'featured']));
+  .where(
+    duckDbArrayContained(products.tags, ['electronics', 'sale', 'featured'])
+  );
 
 // Check if arrays overlap
 const results = await db
@@ -258,7 +275,7 @@ import { migrate } from '@leonardovida-md/drizzle-neo-duckdb';
 await migrate(db, { migrationsFolder: './drizzle' });
 ```
 
-Migration metadata is stored in `drizzle.__drizzle_migrations` by default. See [Migrations Documentation](./docs/migrations.md) for configuration options.
+Migration metadata is stored in `drizzle.__drizzle_migrations` by default. See [Migrations Documentation](https://leonardovida-md.github.io/drizzle-neo-duckdb/guide/migrations) for configuration options.
 
 ## Schema Introspection
 
@@ -283,7 +300,7 @@ const result = await introspect(db, {
 console.log(result.files.schemaTs);
 ```
 
-See [Introspection Documentation](./docs/introspection.md) for all options.
+See [Introspection Documentation](https://leonardovida-md.github.io/drizzle-neo-duckdb/guide/introspection) for all options.
 
 ## Configuration Options
 
@@ -307,22 +324,23 @@ const db = drizzle(connection, {
 
 This connector aims for compatibility with Drizzle's Postgres driver but has some differences:
 
-| Feature | Status |
-|---------|--------|
-| Basic CRUD operations | Full support |
-| Joins and subqueries | Full support |
-| Transactions | No savepoints (nested transactions reuse outer) |
-| JSON/JSONB columns | Use `duckDbJson()` instead |
-| Prepared statements | No statement caching |
-| Streaming results | Results are materialized |
+| Feature               | Status                                                     |
+| --------------------- | ---------------------------------------------------------- |
+| Basic CRUD operations | Full support                                               |
+| Joins and subqueries  | Full support                                               |
+| Transactions          | No savepoints (nested transactions reuse outer)            |
+| JSON/JSONB columns    | Use `duckDbJson()` instead                                 |
+| Prepared statements   | No statement caching                                       |
+| Streaming results     | Materialized by default; use `executeBatches()` for chunks |
 
-See [Limitations Documentation](./docs/limitations.md) for details.
+See [Limitations Documentation](https://leonardovida-md.github.io/drizzle-neo-duckdb/guide/limitations) for details.
 
 ## Examples
 
 - **[MotherDuck NYC Taxi](./example/motherduck-nyc.ts)** — Query the built-in NYC taxi dataset from MotherDuck cloud
 
 Run examples:
+
 ```bash
 MOTHERDUCK_TOKEN=your_token bun example/motherduck-nyc.ts
 ```

package/dist/client.d.ts

@@ -8,3 +8,15 @@ export interface PrepareParamsOptions {
 export declare function prepareParams(params: unknown[], options?: PrepareParamsOptions): unknown[];
 export declare function closeClientConnection(connection: DuckDBConnection): Promise<void>;
 export declare function executeOnClient(client: DuckDBClientLike, query: string, params: unknown[]): Promise<RowData[]>;
+export interface ExecuteInBatchesOptions {
+    rowsPerChunk?: number;
+}
+/**
+ * Stream results from DuckDB in batches to avoid fully materializing rows in JS.
+ */
+export declare function executeInBatches(client: DuckDBClientLike, query: string, params: unknown[], options?: ExecuteInBatchesOptions): AsyncGenerator<RowData[], void, void>;
+/**
+ * Return columnar results when the underlying node-api exposes an Arrow/columnar API.
+ * Falls back to column-major JS arrays when Arrow is unavailable.
+ */
+export declare function executeArrowOnClient(client: DuckDBClientLike, query: string, params: unknown[]): Promise<unknown>;

package/dist/columns.d.ts

@@ -1,5 +1,6 @@
 import { type SQL } from 'drizzle-orm';
 import type { SQLWrapper } from 'drizzle-orm/sql/sql';
+import { type ListValueWrapper, type ArrayValueWrapper, type MapValueWrapper, type BlobValueWrapper, type JsonValueWrapper } from './value-wrappers.ts';
 type IntColType = 'SMALLINT' | 'INTEGER' | 'BIGINT' | 'HUGEINT' | 'USMALLINT' | 'UINTEGER' | 'UBIGINT' | 'UHUGEINT' | 'INT' | 'INT16' | 'INT32' | 'INT64' | 'INT128' | 'LONG' | 'VARINT';
 type FloatColType = 'FLOAT' | 'DOUBLE';
 type StringColType = 'STRING' | 'VARCHAR' | 'TEXT';
@@ -16,7 +17,7 @@ export declare const duckDbList: <TData = unknown>(name: string, elementType: An
     dataType: "custom";
     columnType: "PgCustomColumn";
     data: TData[];
-    driverParam: string | unknown[] | SQL<unknown>;
+    driverParam: string | ListValueWrapper | unknown[];
     enumValues: undefined;
 }>;
 export declare const duckDbArray: <TData = unknown>(name: string, elementType: AnyColType, fixedLength?: number) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
@@ -24,7 +25,7 @@ export declare const duckDbArray: <TData = unknown>(name: string, elementType: A
     dataType: "custom";
     columnType: "PgCustomColumn";
     data: TData[];
-    driverParam: string | unknown[] | SQL<unknown>;
+    driverParam: string | unknown[] | ArrayValueWrapper;
     enumValues: undefined;
 }>;
 export declare const duckDbMap: <TData extends Record<string, any>>(name: string, valueType: AnyColType | ListColType | ArrayColType) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
@@ -32,7 +33,7 @@ export declare const duckDbMap: <TData extends Record<string, any>>(name: string
     dataType: "custom";
     columnType: "PgCustomColumn";
     data: TData;
-    driverParam: TData;
+    driverParam: MapValueWrapper | TData;
     enumValues: undefined;
 }>;
 export declare const duckDbStruct: <TData extends Record<string, any>>(name: string, schema: Record<string, Primitive>) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
@@ -43,12 +44,19 @@ export declare const duckDbStruct: <TData extends Record<string, any>>(name: str
     driverParam: TData;
     enumValues: undefined;
 }>;
+/**
+ * JSON column type that wraps values and delays JSON.stringify() to binding time.
+ * This ensures consistent handling with other wrapped types.
+ *
+ * Note: DuckDB stores JSON as VARCHAR internally, so the final binding
+ * is always a stringified JSON value.
+ */
 export declare const duckDbJson: <TData = unknown>(name: string) => import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
     name: string;
     dataType: "custom";
     columnType: "PgCustomColumn";
     data: TData;
-    driverParam: string | SQL<unknown>;
+    driverParam: string | JsonValueWrapper | SQL<unknown>;
     enumValues: undefined;
 }>;
 export declare const duckDbBlob: {
@@ -56,24 +64,24 @@ export declare const duckDbBlob: {
         name: "";
         dataType: "custom";
         columnType: "PgCustomColumn";
-        data: Buffer;
-        driverParam: unknown;
+        data: Buffer<ArrayBufferLike>;
+        driverParam: BlobValueWrapper;
         enumValues: undefined;
     }>;
     <TConfig extends Record<string, any>>(fieldConfig?: TConfig | undefined): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
         name: "";
         dataType: "custom";
         columnType: "PgCustomColumn";
-        data: Buffer;
-        driverParam: unknown;
+        data: Buffer<ArrayBufferLike>;
+        driverParam: BlobValueWrapper;
         enumValues: undefined;
     }>;
     <TName extends string>(dbName: TName, fieldConfig?: unknown): import("drizzle-orm/pg-core").PgCustomColumnBuilder<{
         name: TName;
         dataType: "custom";
         columnType: "PgCustomColumn";
-        data: Buffer;
-        driverParam: unknown;
+        data: Buffer<ArrayBufferLike>;
+        driverParam: BlobValueWrapper;
         enumValues: undefined;
     }>;
 };

package/dist/driver.d.ts

@@ -4,10 +4,12 @@ import { PgDatabase } from 'drizzle-orm/pg-core/db';
 import type { SelectedFields } from 'drizzle-orm/pg-core/query-builders';
 import { type ExtractTablesWithRelations, type RelationalSchemaConfig, type TablesRelationalConfig } from 'drizzle-orm/relations';
 import { type DrizzleConfig } from 'drizzle-orm/utils';
+import type { SQL } from 'drizzle-orm/sql/sql';
 import type { DuckDBClientLike, DuckDBQueryResultHKT, DuckDBTransaction } from './session.ts';
 import { DuckDBSession } from './session.ts';
 import { DuckDBDialect } from './dialect.ts';
 import { DuckDBSelectBuilder } from './select-builder.ts';
+import type { ExecuteInBatchesOptions, RowData } from './client.ts';
 export interface PgDriverOptions {
     logger?: Logger;
     rewriteArrays?: boolean;
@@ -33,5 +35,7 @@ export declare class DuckDBDatabase<TFullSchema extends Record<string, unknown>
     constructor(dialect: DuckDBDialect, session: DuckDBSession<TFullSchema, TSchema>, schema: RelationalSchemaConfig<TSchema> | undefined);
     select(): DuckDBSelectBuilder<undefined>;
     select<TSelection extends SelectedFields>(fields: TSelection): DuckDBSelectBuilder<TSelection>;
+    executeBatches<T extends RowData = RowData>(query: SQL, options?: ExecuteInBatchesOptions): AsyncGenerator<T[], void, void>;
+    executeArrow(query: SQL): Promise<unknown>;
     transaction<T>(transaction: (tx: DuckDBTransaction<TFullSchema, TSchema>) => Promise<T>): Promise<T>;
 }