@duckdbfan/drizzle-duckdb 0.0.7 → 1.3.2

package/src/value-wrappers-core.ts

@@ -0,0 +1,168 @@
+/**
+ * DuckDB wrapper value helpers that are safe for client-side bundles.
+ * These utilities only tag values; conversion to native bindings lives
+ * in value-wrappers.ts to avoid pulling @duckdb/node-api into browsers.
+ */
+export const DUCKDB_VALUE_MARKER = Symbol.for('drizzle-duckdb:value');
+
+export type DuckDBValueKind =
+  | 'list'
+  | 'array'
+  | 'struct'
+  | 'map'
+  | 'timestamp'
+  | 'blob'
+  | 'json';
+
+export interface DuckDBValueWrapper<
+  TKind extends DuckDBValueKind = DuckDBValueKind,
+  TData = unknown,
+> {
+  readonly [DUCKDB_VALUE_MARKER]: true;
+  readonly kind: TKind;
+  readonly data: TData;
+}
+
+export interface ListValueWrapper extends DuckDBValueWrapper<
+  'list',
+  unknown[]
+> {
+  readonly elementType?: string;
+}
+
+export interface ArrayValueWrapper extends DuckDBValueWrapper<
+  'array',
+  unknown[]
+> {
+  readonly elementType?: string;
+  readonly fixedLength?: number;
+}
+
+export interface StructValueWrapper extends DuckDBValueWrapper<
+  'struct',
+  Record<string, unknown>
+> {
+  readonly schema?: Record<string, string>;
+}
+
+export interface MapValueWrapper extends DuckDBValueWrapper<
+  'map',
+  Record<string, unknown>
+> {
+  readonly valueType?: string;
+}
+
+export interface TimestampValueWrapper extends DuckDBValueWrapper<
+  'timestamp',
+  Date | string | number | bigint
+> {
+  readonly withTimezone: boolean;
+  readonly precision?: number;
+}
+
+export interface BlobValueWrapper extends DuckDBValueWrapper<
+  'blob',
+  Buffer | Uint8Array
+> {}
+
+export interface JsonValueWrapper extends DuckDBValueWrapper<'json', unknown> {}
+
+export type AnyDuckDBValueWrapper =
+  | ListValueWrapper
+  | ArrayValueWrapper
+  | StructValueWrapper
+  | MapValueWrapper
+  | TimestampValueWrapper
+  | BlobValueWrapper
+  | JsonValueWrapper;
+
+export function isDuckDBWrapper(
+  value: unknown
+): value is AnyDuckDBValueWrapper {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    DUCKDB_VALUE_MARKER in value &&
+    (value as DuckDBValueWrapper)[DUCKDB_VALUE_MARKER] === true
+  );
+}
+
+export function wrapList(
+  data: unknown[],
+  elementType?: string
+): ListValueWrapper {
+  return {
+    [DUCKDB_VALUE_MARKER]: true,
+    kind: 'list',
+    data,
+    elementType,
+  };
+}
+
+export function wrapArray(
+  data: unknown[],
+  elementType?: string,
+  fixedLength?: number
+): ArrayValueWrapper {
+  return {
+    [DUCKDB_VALUE_MARKER]: true,
+    kind: 'array',
+    data,
+    elementType,
+    fixedLength,
+  };
+}
+
+export function wrapStruct(
+  data: Record<string, unknown>,
+  schema?: Record<string, string>
+): StructValueWrapper {
+  return {
+    [DUCKDB_VALUE_MARKER]: true,
+    kind: 'struct',
+    data,
+    schema,
+  };
+}
+
+export function wrapMap(
+  data: Record<string, unknown>,
+  valueType?: string
+): MapValueWrapper {
+  return {
+    [DUCKDB_VALUE_MARKER]: true,
+    kind: 'map',
+    data,
+    valueType,
+  };
+}
+
+export function wrapTimestamp(
+  data: Date | string | number | bigint,
+  withTimezone: boolean,
+  precision?: number
+): TimestampValueWrapper {
+  return {
+    [DUCKDB_VALUE_MARKER]: true,
+    kind: 'timestamp',
+    data,
+    withTimezone,
+    precision,
+  };
+}
+
+export function wrapBlob(data: Buffer | Uint8Array): BlobValueWrapper {
+  return {
+    [DUCKDB_VALUE_MARKER]: true,
+    kind: 'blob',
+    data,
+  };
+}
+
+export function wrapJson(data: unknown): JsonValueWrapper {
+  return {
+    [DUCKDB_VALUE_MARKER]: true,
+    kind: 'json',
+    data,
+  };
+}

package/src/value-wrappers.ts

@@ -0,0 +1,165 @@
+import {
+  listValue,
+  arrayValue,
+  structValue,
+  mapValue,
+  blobValue,
+  timestampValue,
+  timestampTZValue,
+  type DuckDBValue,
+  type DuckDBMapEntry,
+} from '@duckdb/node-api';
+import {
+  DUCKDB_VALUE_MARKER,
+  isDuckDBWrapper,
+  wrapArray,
+  wrapBlob,
+  wrapJson,
+  wrapList,
+  wrapMap,
+  wrapStruct,
+  wrapTimestamp,
+  type AnyDuckDBValueWrapper,
+  type DuckDBValueWrapper,
+  type ArrayValueWrapper,
+  type BlobValueWrapper,
+  type JsonValueWrapper,
+  type ListValueWrapper,
+  type MapValueWrapper,
+  type StructValueWrapper,
+  type TimestampValueWrapper,
+  type DuckDBValueKind,
+} from './value-wrappers-core.ts';
+
+/**
+ * Convert a Date/string/epoch number to microseconds since Unix epoch.
+ * Handles Date objects, ISO-like strings, bigint, and millisecond numbers.
+ */
+function dateToMicros(value: Date | string | number | bigint): bigint {
+  if (value instanceof Date) {
+    return BigInt(value.getTime()) * 1000n;
+  }
+
+  if (typeof value === 'bigint') {
+    // Assume bigint already in microseconds (DuckDB default)
+    return value;
+  }
+
+  if (typeof value === 'number') {
+    // Assume JS milliseconds
+    return BigInt(Math.trunc(value)) * 1000n;
+  }
+
+  // For strings, normalize the format for reliable parsing
+  // Handle both 'YYYY-MM-DD HH:MM:SS' and 'YYYY-MM-DDTHH:MM:SS' formats
+  let normalized = value;
+  if (!value.includes('T') && value.includes(' ')) {
+    // Convert 'YYYY-MM-DD HH:MM:SS' to ISO format
+    normalized = value.replace(' ', 'T');
+  }
+  // Add 'Z' suffix if no timezone offset to treat as UTC
+  if (!normalized.endsWith('Z') && !/[+-]\d{2}:?\d{2}$/.test(normalized)) {
+    normalized += 'Z';
+  }
+
+  const date = new Date(normalized);
+  if (isNaN(date.getTime())) {
+    throw new Error(`Invalid timestamp string: ${value}`);
+  }
+  return BigInt(date.getTime()) * 1000n;
+}
+
+/**
+ * Convert Buffer or Uint8Array to Uint8Array.
+ */
+function toUint8Array(data: Buffer | Uint8Array): Uint8Array {
+  return data instanceof Uint8Array && !(data instanceof Buffer)
+    ? data
+    : new Uint8Array(data);
+}
+
+/**
+ * Convert struct entries to DuckDB struct value entries.
+ */
+function convertStructEntries(
+  data: Record<string, unknown>,
+  toValue: (v: unknown) => DuckDBValue
+): Record<string, DuckDBValue> {
+  const entries: Record<string, DuckDBValue> = {};
+  for (const [key, val] of Object.entries(data)) {
+    entries[key] = toValue(val);
+  }
+  return entries;
+}
+
+/**
+ * Convert map entries to DuckDB map entry format.
+ */
+function convertMapEntries(
+  data: Record<string, unknown>,
+  toValue: (v: unknown) => DuckDBValue
+): DuckDBMapEntry[] {
+  return Object.entries(data).map(([key, val]) => ({
+    key: key as DuckDBValue,
+    value: toValue(val),
+  }));
+}
+
+/**
+ * Convert a wrapper to a DuckDB Node API value.
+ * Uses exhaustive switch for compile-time safety.
+ */
+export function wrapperToNodeApiValue(
+  wrapper: AnyDuckDBValueWrapper,
+  toValue: (v: unknown) => DuckDBValue
+): DuckDBValue {
+  switch (wrapper.kind) {
+    case 'list':
+      return listValue(wrapper.data.map(toValue));
+    case 'array':
+      return arrayValue(wrapper.data.map(toValue));
+    case 'struct':
+      return structValue(convertStructEntries(wrapper.data, toValue));
+    case 'map':
+      return mapValue(convertMapEntries(wrapper.data, toValue));
+    case 'timestamp':
+      return wrapper.withTimezone
+        ? timestampTZValue(dateToMicros(wrapper.data))
+        : timestampValue(dateToMicros(wrapper.data));
+    case 'blob':
+      return blobValue(toUint8Array(wrapper.data));
+    case 'json':
+      // JSON is stored as VARCHAR in DuckDB - stringify at binding time
+      return JSON.stringify(wrapper.data);
+    default: {
+      // Exhaustive check - TypeScript will error if a case is missing
+      const _exhaustive: never = wrapper;
+      throw new Error(
+        `Unknown wrapper kind: ${(_exhaustive as AnyDuckDBValueWrapper).kind}`
+      );
+    }
+  }
+}
+
+// Re-export core helpers for convenience and backward compatibility.
+export {
+  DUCKDB_VALUE_MARKER,
+  isDuckDBWrapper,
+  wrapArray,
+  wrapBlob,
+  wrapJson,
+  wrapList,
+  wrapMap,
+  wrapStruct,
+  wrapTimestamp,
+  type AnyDuckDBValueWrapper,
+  type DuckDBValueWrapper,
+  type ArrayValueWrapper,
+  type BlobValueWrapper,
+  type JsonValueWrapper,
+  type ListValueWrapper,
+  type MapValueWrapper,
+  type StructValueWrapper,
+  type TimestampValueWrapper,
+  type DuckDBValueKind,
+} from './value-wrappers-core.ts';