@duckdb/node-api 1.2.0-alpha.14 → 1.2.0-alpha.15

package/README.md

@@ -644,7 +644,7 @@ await connection.run(
   `create or replace table target_table(i integer, v varchar)`
 );
 
-const appender = await connection.createAppender('main', 'target_table');
+const appender = await connection.createAppender('target_table');
 
 appender.appendInteger(42);
 appender.appendVarchar('duck');
@@ -670,7 +670,7 @@ await connection.run(
   `create or replace table target_table(i integer, v varchar)`
 );
 
-const appender = await connection.createAppender('main', 'target_table');
+const appender = await connection.createAppender('target_table');
 
 const chunk = DuckDBDataChunk.create([INTEGER, VARCHAR]);
 chunk.setColumns([

package/lib/DuckDBAppender.d.ts

@@ -1,7 +1,7 @@
 import duckdb from '@duckdb/node-bindings';
 import { DuckDBDataChunk } from './DuckDBDataChunk';
-import { DuckDBType } from './DuckDBType';
-import { DuckDBDateValue, DuckDBIntervalValue, DuckDBTimestampValue, DuckDBTimeValue } from './values';
+import { DuckDBArrayType, DuckDBEnumType, DuckDBListType, DuckDBStructType, DuckDBType } from './DuckDBType';
+import { DuckDBArrayValue, DuckDBBitValue, DuckDBDateValue, DuckDBDecimalValue, DuckDBIntervalValue, DuckDBListValue, DuckDBStructValue, DuckDBTimestampMillisecondsValue, DuckDBTimestampNanosecondsValue, DuckDBTimestampSecondsValue, DuckDBTimestampTZValue, DuckDBTimestampValue, DuckDBTimeTZValue, DuckDBTimeValue, DuckDBUUIDValue, DuckDBValue } from './values';
 export declare class DuckDBAppender {
     private readonly appender;
     constructor(appender: duckdb.Appender);
@@ -22,14 +22,28 @@ export declare class DuckDBAppender {
     appendUInteger(value: number): void;
     appendUBigInt(value: bigint): void;
     appendUHugeInt(value: bigint): void;
+    appendDecimal(value: DuckDBDecimalValue): void;
     appendFloat(value: number): void;
     appendDouble(value: number): void;
     appendDate(value: DuckDBDateValue): void;
     appendTime(value: DuckDBTimeValue): void;
+    appendTimeTZ(value: DuckDBTimeTZValue): void;
     appendTimestamp(value: DuckDBTimestampValue): void;
+    appendTimestampTZ(value: DuckDBTimestampTZValue): void;
+    appendTimestampSeconds(value: DuckDBTimestampSecondsValue): void;
+    appendTimestampMilliseconds(value: DuckDBTimestampMillisecondsValue): void;
+    appendTimestampNanoseconds(value: DuckDBTimestampNanosecondsValue): void;
     appendInterval(value: DuckDBIntervalValue): void;
     appendVarchar(value: string): void;
     appendBlob(value: Uint8Array): void;
+    appendEnum(value: string, type: DuckDBEnumType): void;
+    appendList(value: DuckDBListValue, type: DuckDBListType): void;
+    appendStruct(value: DuckDBStructValue, type: DuckDBStructType): void;
+    appendArray(value: DuckDBArrayValue, type: DuckDBArrayType): void;
+    appendUUID(value: DuckDBUUIDValue): void;
+    appendBit(value: DuckDBBitValue): void;
+    appendVarInt(value: bigint): void;
     appendNull(): void;
+    appendValue(value: DuckDBValue, type: DuckDBType): void;
     appendDataChunk(dataChunk: DuckDBDataChunk): void;
 }

package/lib/DuckDBAppender.js

@@ -5,7 +5,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DuckDBAppender = void 0;
 const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
+const createValue_1 = require("./createValue");
 const DuckDBLogicalType_1 = require("./DuckDBLogicalType");
+const DuckDBType_1 = require("./DuckDBType");
 class DuckDBAppender {
     appender;
     constructor(appender) {
@@ -62,7 +64,10 @@ class DuckDBAppender {
     appendUHugeInt(value) {
         node_bindings_1.default.append_uhugeint(this.appender, value);
     }
-    // TODO: append DECIMAL?
+    appendDecimal(value) {
+        // The width and scale of the DECIMAL type here aren't actually used.
+        this.appendValue(value, (0, DuckDBType_1.DECIMAL)(value.width, value.scale));
+    }
     appendFloat(value) {
         node_bindings_1.default.append_float(this.appender, value);
     }
@@ -75,11 +80,24 @@ class DuckDBAppender {
     appendTime(value) {
         node_bindings_1.default.append_time(this.appender, value);
     }
+    appendTimeTZ(value) {
+        this.appendValue(value, DuckDBType_1.TIMETZ);
+    }
     appendTimestamp(value) {
         node_bindings_1.default.append_timestamp(this.appender, value);
     }
-    // TODO: append TIMESTAMPS_S/_MS/_NS?
-    // TODO: append TIME_TZ/TIMESTAMP_TZ?
+    appendTimestampTZ(value) {
+        this.appendValue(value, DuckDBType_1.TIMESTAMPTZ);
+    }
+    appendTimestampSeconds(value) {
+        this.appendValue(value, DuckDBType_1.TIMESTAMP_S);
+    }
+    appendTimestampMilliseconds(value) {
+        this.appendValue(value, DuckDBType_1.TIMESTAMP_MS);
+    }
+    appendTimestampNanoseconds(value) {
+        this.appendValue(value, DuckDBType_1.TIMESTAMP_NS);
+    }
     appendInterval(value) {
         node_bindings_1.default.append_interval(this.appender, value);
     }
@@ -89,13 +107,35 @@ class DuckDBAppender {
     appendBlob(value) {
         node_bindings_1.default.append_blob(this.appender, value);
     }
-    // TODO: append ENUM?
-    // TODO: append nested types? (ARRAY, LIST, STRUCT, MAP, UNION)
-    // TODO: append UUID?
-    // TODO: append BIT?
+    appendEnum(value, type) {
+        this.appendValue(value, type);
+    }
+    appendList(value, type) {
+        this.appendValue(value, type);
+    }
+    appendStruct(value, type) {
+        this.appendValue(value, type);
+    }
+    // TODO: MAP (when DuckDB C API supports creating MAP values)
+    appendArray(value, type) {
+        this.appendValue(value, type);
+    }
+    // TODO: UNION (when DuckDB C API supports creating UNION values)
+    appendUUID(value) {
+        this.appendValue(value, DuckDBType_1.UUID);
+    }
+    appendBit(value) {
+        this.appendValue(value, DuckDBType_1.BIT);
+    }
+    appendVarInt(value) {
+        this.appendValue(value, DuckDBType_1.VARINT);
+    }
     appendNull() {
         node_bindings_1.default.append_null(this.appender);
     }
+    appendValue(value, type) {
+        node_bindings_1.default.append_value(this.appender, (0, createValue_1.createValue)(type, value));
+    }
     appendDataChunk(dataChunk) {
         node_bindings_1.default.append_data_chunk(this.appender, dataChunk.chunk);
     }

package/lib/DuckDBConnection.d.ts

@@ -30,5 +30,5 @@ export declare class DuckDBConnection {
     startStream(sql: string, values?: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): Promise<DuckDBPendingResult>;
     prepare(sql: string): Promise<DuckDBPreparedStatement>;
     extractStatements(sql: string): Promise<DuckDBExtractedStatements>;
-    createAppender(schema: string, table: string): Promise<DuckDBAppender>;
+    createAppender(table: string, schema?: string | null, catalog?: string | null): Promise<DuckDBAppender>;
 }

package/lib/DuckDBConnection.js

@@ -98,8 +98,8 @@ class DuckDBConnection {
         }
         return new DuckDBExtractedStatements_1.DuckDBExtractedStatements(this.connection, extracted_statements, statement_count);
     }
-    async createAppender(schema, table) {
-        return new DuckDBAppender_1.DuckDBAppender(node_bindings_1.default.appender_create(this.connection, schema, table));
+    async createAppender(table, schema, catalog) {
+        return new DuckDBAppender_1.DuckDBAppender(node_bindings_1.default.appender_create_ext(this.connection, catalog ?? null, schema ?? null, table));
     }
 }
 exports.DuckDBConnection = DuckDBConnection;

package/lib/DuckDBPreparedStatement.d.ts

@@ -3,10 +3,10 @@ import { DuckDBMaterializedResult } from './DuckDBMaterializedResult';
 import { DuckDBPendingResult } from './DuckDBPendingResult';
 import { DuckDBResult } from './DuckDBResult';
 import { DuckDBResultReader } from './DuckDBResultReader';
-import { DuckDBArrayType, DuckDBListType, DuckDBStructType, DuckDBType } from './DuckDBType';
+import { DuckDBArrayType, DuckDBEnumType, DuckDBListType, DuckDBStructType, DuckDBType } from './DuckDBType';
 import { DuckDBTypeId } from './DuckDBTypeId';
 import { StatementType } from './enums';
-import { DuckDBArrayValue, DuckDBDateValue, DuckDBDecimalValue, DuckDBIntervalValue, DuckDBListValue, DuckDBStructValue, DuckDBTimestampTZValue, DuckDBTimestampValue, DuckDBTimeTZValue, DuckDBTimeValue, DuckDBValue } from './values';
+import { DuckDBArrayValue, DuckDBBitValue, DuckDBDateValue, DuckDBDecimalValue, DuckDBIntervalValue, DuckDBListValue, DuckDBStructValue, DuckDBTimestampMillisecondsValue, DuckDBTimestampNanosecondsValue, DuckDBTimestampSecondsValue, DuckDBTimestampTZValue, DuckDBTimestampValue, DuckDBTimeTZValue, DuckDBTimeValue, DuckDBUUIDValue, DuckDBValue } from './values';
 export declare class DuckDBPreparedStatement {
     private readonly prepared_statement;
     constructor(prepared_statement: duckdb.PreparedStatement);
@@ -28,6 +28,7 @@ export declare class DuckDBPreparedStatement {
     bindUInteger(parameterIndex: number, value: number): void;
     bindUBigInt(parameterIndex: number, value: bigint): void;
     bindUHugeInt(parameterIndex: number, value: bigint): void;
+    bindVarInt(parameterIndex: number, value: bigint): void;
     bindDecimal(parameterIndex: number, value: DuckDBDecimalValue): void;
     bindFloat(parameterIndex: number, value: number): void;
     bindDouble(parameterIndex: number, value: number): void;
@@ -36,12 +37,18 @@ export declare class DuckDBPreparedStatement {
     bindTimeTZ(parameterIndex: number, value: DuckDBTimeTZValue): void;
     bindTimestamp(parameterIndex: number, value: DuckDBTimestampValue): void;
     bindTimestampTZ(parameterIndex: number, value: DuckDBTimestampTZValue): void;
+    bindTimestampSeconds(parameterIndex: number, value: DuckDBTimestampSecondsValue): void;
+    bindTimestampMilliseconds(parameterIndex: number, value: DuckDBTimestampMillisecondsValue): void;
+    bindTimestampNanoseconds(parameterIndex: number, value: DuckDBTimestampNanosecondsValue): void;
     bindInterval(parameterIndex: number, value: DuckDBIntervalValue): void;
     bindVarchar(parameterIndex: number, value: string): void;
     bindBlob(parameterIndex: number, value: Uint8Array): void;
+    bindEnum(parameterIndex: number, value: string, type: DuckDBEnumType): void;
     bindArray(parameterIndex: number, value: DuckDBArrayValue, type: DuckDBArrayType): void;
     bindList(parameterIndex: number, value: DuckDBListValue, type: DuckDBListType): void;
     bindStruct(parameterIndex: number, value: DuckDBStructValue, type: DuckDBStructType): void;
+    bindUUID(parameterIndex: number, value: DuckDBUUIDValue): void;
+    bindBit(parameterIndex: number, value: DuckDBBitValue): void;
     bindNull(parameterIndex: number): void;
     bindValue(parameterIndex: number, value: DuckDBValue, type: DuckDBType): void;
     bind(values: DuckDBValue[] | Record<string, DuckDBValue>, types?: DuckDBType[] | Record<string, DuckDBType | undefined>): void;

package/lib/DuckDBPreparedStatement.js

@@ -72,6 +72,9 @@ class DuckDBPreparedStatement {
     bindUHugeInt(parameterIndex, value) {
         node_bindings_1.default.bind_uhugeint(this.prepared_statement, parameterIndex, value);
     }
+    bindVarInt(parameterIndex, value) {
+        this.bindValue(parameterIndex, value, DuckDBType_1.VARINT);
+    }
     bindDecimal(parameterIndex, value) {
         node_bindings_1.default.bind_decimal(this.prepared_statement, parameterIndex, value);
     }
@@ -96,7 +99,15 @@ class DuckDBPreparedStatement {
     bindTimestampTZ(parameterIndex, value) {
         this.bindValue(parameterIndex, value, DuckDBType_1.TIMESTAMPTZ);
     }
-    // TODO: bind TIMESTAMPS_S/_MS/_NS
+    bindTimestampSeconds(parameterIndex, value) {
+        this.bindValue(parameterIndex, value, DuckDBType_1.TIMESTAMP_S);
+    }
+    bindTimestampMilliseconds(parameterIndex, value) {
+        this.bindValue(parameterIndex, value, DuckDBType_1.TIMESTAMP_MS);
+    }
+    bindTimestampNanoseconds(parameterIndex, value) {
+        this.bindValue(parameterIndex, value, DuckDBType_1.TIMESTAMP_NS);
+    }
     bindInterval(parameterIndex, value) {
         node_bindings_1.default.bind_interval(this.prepared_statement, parameterIndex, value);
     }
@@ -106,7 +117,9 @@ class DuckDBPreparedStatement {
     bindBlob(parameterIndex, value) {
         node_bindings_1.default.bind_blob(this.prepared_statement, parameterIndex, value);
     }
-    // TODO: bind ENUM
+    bindEnum(parameterIndex, value, type) {
+        this.bindValue(parameterIndex, value, type);
+    }
     bindArray(parameterIndex, value, type) {
         this.bindValue(parameterIndex, value, type);
     }
@@ -117,8 +130,12 @@ class DuckDBPreparedStatement {
         this.bindValue(parameterIndex, value, type);
     }
     // TODO: bind MAP, UNION
-    // TODO: bind UUID
-    // TODO: bind BIT
+    bindUUID(parameterIndex, value) {
+        this.bindValue(parameterIndex, value, DuckDBType_1.UUID);
+    }
+    bindBit(parameterIndex, value) {
+        this.bindValue(parameterIndex, value, DuckDBType_1.BIT);
+    }
     bindNull(parameterIndex) {
         node_bindings_1.default.bind_null(this.prepared_statement, parameterIndex);
     }

package/lib/DuckDBVector.js

@@ -74,7 +74,8 @@ function getVarIntFromBytes(bytes) {
     const positive = (firstByte & 0x80) > 0;
     const uint64Mask = positive ? 0n : 0xffffffffffffffffn;
     const uint8Mask = positive ? 0 : 0xff;
-    const dv = new DataView(bytes.buffer, bytes.byteOffset + 3, bytes.byteLength - 3);
+    const dv = new DataView(// bytes is big endian
+    bytes.buffer, bytes.byteOffset + 3, bytes.byteLength - 3);
     const lastUint64Offset = dv.byteLength - 8;
     let offset = 0;
     let result = 0n;
@@ -89,26 +90,29 @@ function getVarIntFromBytes(bytes) {
     return positive ? result : -result;
 }
 function getBytesFromVarInt(varint) {
-    const numberBytes = [];
+    const numberBytes = []; // little endian
+    const negative = varint < 0;
     if (varint === 0n) {
         numberBytes.push(0);
     }
     else {
-        while (varint !== 0n) {
-            numberBytes.push(Number(BigInt.asUintN(8, varint)));
-            varint >>= 8n;
+        let vi = varint < 0 ? -varint : varint;
+        while (vi !== 0n) {
+            numberBytes.push(Number(BigInt.asUintN(8, vi)));
+            vi >>= 8n;
         }
     }
-    const varIntBytes = new Uint8Array(3 + numberBytes.length);
+    const varIntBytes = new Uint8Array(3 + numberBytes.length); // big endian
     let header = 0x800000 | numberBytes.length;
-    if (varint < 0) {
+    if (negative) {
         header = ~header;
     }
     varIntBytes[0] = 0xff & (header >> 16);
     varIntBytes[1] = 0xff & (header >> 8);
     varIntBytes[2] = 0xff & header;
     for (let i = 0; i < numberBytes.length; i++) {
-        varIntBytes[3 + i] = numberBytes[i];
+        const byte = numberBytes[numberBytes.length - 1 - i];
+        varIntBytes[3 + i] = negative ? ~byte : byte;
     }
     return varIntBytes;
 }
@@ -2176,7 +2180,7 @@ class DuckDBUUIDVector extends DuckDBVector {
     }
     getItem(itemIndex) {
         return this.validity.itemValid(itemIndex)
-            ? new values_1.DuckDBUUIDValue(getInt128(this.dataView, itemIndex * 16))
+            ? values_1.DuckDBUUIDValue.fromStoredHugeInt(getInt128(this.dataView, itemIndex * 16))
             : null;
     }
     setItem(itemIndex, value) {

package/lib/createValue.js

@@ -8,7 +8,11 @@ const node_bindings_1 = __importDefault(require("@duckdb/node-bindings"));
 const DuckDBTypeId_1 = require("./DuckDBTypeId");
 const values_1 = require("./values");
 function createValue(type, input) {
-    switch (type.typeId) {
+    if (input === null) {
+        return node_bindings_1.default.create_null_value();
+    }
+    const { typeId } = type;
+    switch (typeId) {
         case DuckDBTypeId_1.DuckDBTypeId.BOOLEAN:
             if (typeof input === 'boolean') {
                 return node_bindings_1.default.create_bool(input);
@@ -105,15 +109,30 @@ function createValue(type, input) {
             }
             throw new Error(`input is not a DuckDBBlobValue`);
         case DuckDBTypeId_1.DuckDBTypeId.DECIMAL:
-            throw new Error(`not yet implemented for DECIMAL`); // TODO: implement when available in 1.2.0
+            if (input instanceof values_1.DuckDBDecimalValue) {
+                return node_bindings_1.default.create_decimal(input);
+            }
+            throw new Error(`input is not a DuckDBDecimalValue`);
         case DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_S:
-            throw new Error(`not yet implemented for TIMESTAMP_S`); // TODO: implement when available in 1.2.0
+            if (input instanceof values_1.DuckDBTimestampSecondsValue) {
+                return node_bindings_1.default.create_timestamp_s(input);
+            }
+            throw new Error(`input is not a DuckDBTimestampSecondsValue`);
         case DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_MS:
-            throw new Error(`not yet implemented for TIMESTAMP_MS`); // TODO: implement when available in 1.2.0
+            if (input instanceof values_1.DuckDBTimestampMillisecondsValue) {
+                return node_bindings_1.default.create_timestamp_ms(input);
+            }
+            throw new Error(`input is not a DuckDBTimestampMillisecondsValue`);
         case DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_NS:
-            throw new Error(`not yet implemented for TIMESTAMP_NS`); // TODO: implement when available in 1.2.0
+            if (input instanceof values_1.DuckDBTimestampNanosecondsValue) {
+                return node_bindings_1.default.create_timestamp_ns(input);
+            }
+            throw new Error(`input is not a DuckDBTimestampNanosecondsValue`);
         case DuckDBTypeId_1.DuckDBTypeId.ENUM:
-            throw new Error(`not yet implemented for ENUM`); // TODO: implement when available in 1.2.0
+            if (typeof input === 'string') {
+                return node_bindings_1.default.create_enum_value(type.toLogicalType().logical_type, type.indexForValue(input));
+            }
+            throw new Error(`input is not a string`);
         case DuckDBTypeId_1.DuckDBTypeId.LIST:
             if (input instanceof values_1.DuckDBListValue) {
                 if (type.valueType.typeId === DuckDBTypeId_1.DuckDBTypeId.ANY) {
@@ -124,7 +143,7 @@ function createValue(type, input) {
             throw new Error(`input is not a DuckDBListValue`);
         case DuckDBTypeId_1.DuckDBTypeId.STRUCT:
             if (input instanceof values_1.DuckDBStructValue) {
-                if (type.entryTypes.find((type) => type.typeId === DuckDBTypeId_1.DuckDBTypeId.ANY)) {
+                if (type.entryTypes.find((entryType) => entryType.typeId === DuckDBTypeId_1.DuckDBTypeId.ANY)) {
                     throw new Error('Cannot create structs with an entry type of ANY. Specify a specific type.');
                 }
                 return node_bindings_1.default.create_struct_value(type.toLogicalType().logical_type, Object.values(input.entries).map((value, i) => createValue(type.entryTypes[i], value)));
@@ -141,11 +160,17 @@ function createValue(type, input) {
             }
             throw new Error(`input is not a DuckDBArrayValue`);
         case DuckDBTypeId_1.DuckDBTypeId.UUID:
-            throw new Error(`not yet implemented for UUID`); // TODO: implement when available in 1.2.0
+            if (input instanceof values_1.DuckDBUUIDValue) {
+                return node_bindings_1.default.create_uuid(input.toUint128());
+            }
+            throw new Error(`input is not a bigint`);
         case DuckDBTypeId_1.DuckDBTypeId.UNION:
             throw new Error(`not yet implemented for UNION`); // TODO: implement when available, hopefully in 1.2.0
-        case DuckDBTypeId_1.DuckDBTypeId.UNION:
-            throw new Error(`not yet implemented for BIT`); // TODO: implement when available in 1.2.0
+        case DuckDBTypeId_1.DuckDBTypeId.BIT:
+            if (input instanceof values_1.DuckDBBitValue) {
+                return node_bindings_1.default.create_bit(input.data);
+            }
+            throw new Error(`input is not a DuckDBBitValue`);
         case DuckDBTypeId_1.DuckDBTypeId.TIME_TZ:
             if (input instanceof values_1.DuckDBTimeTZValue) {
                 return node_bindings_1.default.create_time_tz_value(input);
@@ -153,16 +178,19 @@ function createValue(type, input) {
             throw new Error(`input is not a DuckDBTimeTZValue`);
         case DuckDBTypeId_1.DuckDBTypeId.TIMESTAMP_TZ:
             if (input instanceof values_1.DuckDBTimestampTZValue) {
-                return node_bindings_1.default.create_timestamp(input); // TODO: change to create_timestamp_tz when available in 1.2.0
+                return node_bindings_1.default.create_timestamp_tz(input);
             }
             throw new Error(`input is not a DuckDBTimestampTZValue`);
         case DuckDBTypeId_1.DuckDBTypeId.ANY:
             throw new Error(`Cannot create values of type ANY. Specify a specific type.`);
         case DuckDBTypeId_1.DuckDBTypeId.VARINT:
-            throw new Error(`not yet implemented for VARINT`); // TODO: implement when available in 1.2.0
+            if (typeof input === 'bigint') {
+                return node_bindings_1.default.create_varint(input);
+            }
+            throw new Error(`input is not a bigint`);
         case DuckDBTypeId_1.DuckDBTypeId.SQLNULL:
-            throw new Error(`not yet implemented for SQLNUll`); // TODO: implement when available in 1.2.0
+            return node_bindings_1.default.create_null_value();
         default:
-            throw new Error(`unrecognized type id ${type.typeId}`);
+            throw new Error(`unrecognized type id ${typeId}`);
     }
 }

package/lib/values/DuckDBUUIDValue.d.ts

@@ -1,8 +1,19 @@
 export declare class DuckDBUUIDValue {
     readonly hugeint: bigint;
-    constructor(hugeint: bigint);
+    private constructor();
+    /** Return the UUID as an unsigned 128-bit integer in a JS BigInt. */
+    toUint128(): bigint;
     toString(): string;
+    /** Create a DuckDBUUIDValue from an unsigned 128-bit integer in a JS BigInt. */
+    static fromUint128(uint128: bigint): DuckDBUUIDValue;
+    /**
+     * Create a DuckDBUUIDValue from a HUGEINT as stored by DuckDB.
+     *
+     * UUID values are stored with their MSB flipped so their numeric ordering matches their string ordering.
+     */
+    static fromStoredHugeInt(hugeint: bigint): DuckDBUUIDValue;
     static readonly Max: DuckDBUUIDValue;
     static readonly Min: DuckDBUUIDValue;
 }
-export declare function uuidValue(hugeint: bigint): DuckDBUUIDValue;
+/** Create a DuckDBUUIDValue from an unsigned 128-bit integer in a JS BigInt. */
+export declare function uuidValue(uint128: bigint): DuckDBUUIDValue;

package/lib/values/DuckDBUUIDValue.js

@@ -7,18 +7,34 @@ class DuckDBUUIDValue {
     constructor(hugeint) {
         this.hugeint = hugeint;
     }
-    toString() {
+    /** Return the UUID as an unsigned 128-bit integer in a JS BigInt. */
+    toUint128() {
         // UUID values are stored with their MSB flipped so their numeric ordering matches their string ordering.
-        const flipped = this.hugeint ^ 0x80000000000000000000000000000000n;
-        // Truncate to 32 hex digits, then prepend with a hex 1, before converting to a hex string.
+        return (this.hugeint ^ 0x80000000000000000000000000000000n) & 0xffffffffffffffffffffffffffffffffn;
+    }
+    toString() {
+        // Prepend with a (hex) 1 before converting to a hex string.
         // This ensures the trailing 32 characters are the hex digits we want, left padded with zeros as needed.
-        const hex = ((flipped & 0xffffffffffffffffffffffffffffffffn) | 0x100000000000000000000000000000000n).toString(16);
+        const hex = (this.toUint128() | 0x100000000000000000000000000000000n).toString(16);
         return `${hex.substring(1, 9)}-${hex.substring(9, 13)}-${hex.substring(13, 17)}-${hex.substring(17, 21)}-${hex.substring(21, 33)}`;
     }
+    /** Create a DuckDBUUIDValue from an unsigned 128-bit integer in a JS BigInt. */
+    static fromUint128(uint128) {
+        return new DuckDBUUIDValue((uint128 ^ 0x80000000000000000000000000000000n) & 0xffffffffffffffffffffffffffffffffn);
+    }
+    /**
+     * Create a DuckDBUUIDValue from a HUGEINT as stored by DuckDB.
+     *
+     * UUID values are stored with their MSB flipped so their numeric ordering matches their string ordering.
+     */
+    static fromStoredHugeInt(hugeint) {
+        return new DuckDBUUIDValue(hugeint);
+    }
     static Max = new DuckDBUUIDValue(2n ** 127n - 1n); //  7fffffffffffffffffffffffffffffff
     static Min = new DuckDBUUIDValue(-(2n ** 127n)); //  80000000000000000000000000000000
 }
 exports.DuckDBUUIDValue = DuckDBUUIDValue;
-function uuidValue(hugeint) {
-    return new DuckDBUUIDValue(hugeint);
+/** Create a DuckDBUUIDValue from an unsigned 128-bit integer in a JS BigInt. */
+function uuidValue(uint128) {
+    return DuckDBUUIDValue.fromUint128(uint128);
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@duckdb/node-api",
-  "version": "1.2.0-alpha.14",
+  "version": "1.2.0-alpha.15",
   "license": "MIT",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "dependencies": {
-    "@duckdb/node-bindings": "1.2.0-alpha.14"
+    "@duckdb/node-bindings": "1.2.0-alpha.15"
   },
   "repository": {
     "type": "git",