@sedrino/drizzle 0.0.1 → 0.0.2

package/README.md

@@ -2,6 +2,11 @@
 
 Utilities for using Temporal with Drizzle (SQLite for now).
 
+## Docs
+
+- `docs/sqlite.md` - SQLite + Drizzle best practices (and how to use this library).
+- `docs/plan.md` - Proposed additions aligned with Mostica best practices.
+
 ## Install
 
 ```bash
@@ -22,9 +27,11 @@ import {
 export const tasks = sqliteTable("tasks", {
   id: text("id").primaryKey(),
   title: text("title").notNull(),
-  dueDate: temporalPlainDateText("due_date").nullable(),
+  // You can either pass explicit DB column names (as shown here), or
+  // omit them and use Drizzle `casing: "snake_case"` (see docs/sqlite.md).
+  dueDate: temporalPlainDateText("due_date"),
   createdAt: temporalInstantEpochMs("created_at_ms").notNull(),
-  startsAt: temporalZonedDateTimeText("starts_at").nullable(),
+  startsAt: temporalZonedDateTimeText("starts_at"),
   // startsAt: zonedDateTimeParts("starts_at"),
 });
 ```

package/dist/sqlite.d.ts

@@ -2,7 +2,7 @@ import { customType, integer, text } from "drizzle-orm/sqlite-core";
 import "temporal-polyfill/global";
 /**
  * Runtime Temporal resolution:
- * - pass { Temporal } from "@js-temporal/polyfill" if needed
+ * - pass { Temporal } from "temporal-polyfill" if needed
  * - otherwise uses globalThis.Temporal
  */
 export type TemporalRuntime = typeof Temporal;
@@ -11,15 +11,27 @@ type ToStringPrecision = {
     smallestUnit?: SmallestUnit;
     roundingMode?: "ceil" | "floor" | "trunc" | "halfExpand";
 };
+/**
+ * SQLite expression for "now" in epoch milliseconds.
+ *
+ * Uses strftime so we include milliseconds (not just whole seconds).
+ * Suitable for `.default(epochMsNow())` on INTEGER columns.
+ */
+export declare const epochMsNow: () => import("drizzle-orm").SQL<number>;
 /** PlainDate -> TEXT "YYYY-MM-DD" */
-export declare const temporalPlainDateText: (name: string, opts?: {
+export declare const temporalPlainDateText: (nameOrOpts?: string | {
+    Temporal?: TemporalRuntime;
+}, maybeOpts?: {
     Temporal?: TemporalRuntime;
 }) => ReturnType<ReturnType<typeof customType<{
     data: Temporal.PlainDate;
     driverData: string;
 }>>>;
 /** PlainTime -> TEXT "HH:mm:ss.sssssssss" (precision controlled via smallestUnit) */
-export declare const temporalPlainTimeText: (name: string, opts?: {
+export declare const temporalPlainTimeText: (nameOrOpts?: string | {
+    Temporal?: TemporalRuntime;
+    precision?: ToStringPrecision;
+}, maybeOpts?: {
     Temporal?: TemporalRuntime;
     precision?: ToStringPrecision;
 }) => ReturnType<ReturnType<typeof customType<{
@@ -27,7 +39,10 @@ export declare const temporalPlainTimeText: (name: string, opts?: {
     driverData: string;
 }>>>;
 /** PlainDateTime -> TEXT "YYYY-MM-DDTHH:mm:ss.sssssssss" */
-export declare const temporalPlainDateTimeText: (name: string, opts?: {
+export declare const temporalPlainDateTimeText: (nameOrOpts?: string | {
+    Temporal?: TemporalRuntime;
+    precision?: ToStringPrecision;
+}, maybeOpts?: {
     Temporal?: TemporalRuntime;
     precision?: ToStringPrecision;
 }) => ReturnType<ReturnType<typeof customType<{
@@ -35,14 +50,18 @@ export declare const temporalPlainDateTimeText: (name: string, opts?: {
     driverData: string;
 }>>>;
 /** PlainYearMonth -> TEXT "YYYY-MM" (plus optional calendar annotation if non-ISO) */
-export declare const temporalPlainYearMonthText: (name: string, opts?: {
+export declare const temporalPlainYearMonthText: (nameOrOpts?: string | {
+    Temporal?: TemporalRuntime;
+}, maybeOpts?: {
     Temporal?: TemporalRuntime;
 }) => ReturnType<ReturnType<typeof customType<{
     data: Temporal.PlainYearMonth;
     driverData: string;
 }>>>;
 /** PlainMonthDay -> TEXT "MM-DD" (plus optional calendar annotation if non-ISO) */
-export declare const temporalPlainMonthDayText: (name: string, opts?: {
+export declare const temporalPlainMonthDayText: (nameOrOpts?: string | {
+    Temporal?: TemporalRuntime;
+}, maybeOpts?: {
     Temporal?: TemporalRuntime;
 }) => ReturnType<ReturnType<typeof customType<{
     data: Temporal.PlainMonthDay;
@@ -53,7 +72,9 @@ export declare const temporalPlainMonthDayText: (name: string, opts?: {
  * Note: if millis/micros/nanos exceed 999, parsing back yields an
  * equal-but-differently-balanced Duration.
  */
-export declare const temporalDurationText: (name: string, opts?: {
+export declare const temporalDurationText: (nameOrOpts?: string | {
+    Temporal?: TemporalRuntime;
+}, maybeOpts?: {
     Temporal?: TemporalRuntime;
 }) => ReturnType<ReturnType<typeof customType<{
     data: Temporal.Duration;
@@ -64,7 +85,9 @@ export declare const temporalDurationText: (name: string, opts?: {
  * Great for sorting/filtering by actual time.
  * Tradeoff: millisecond precision only.
  */
-export declare const temporalInstantEpochMs: (name: string, opts?: {
+export declare const temporalInstantEpochMs: (nameOrOpts?: string | {
+    Temporal?: TemporalRuntime;
+}, maybeOpts?: {
     Temporal?: TemporalRuntime;
 }) => ReturnType<ReturnType<typeof customType<{
     data: Temporal.Instant;
@@ -75,7 +98,10 @@ export declare const temporalInstantEpochMs: (name: string, opts?: {
  * Instant (lossless) -> TEXT ISO string, e.g. "2026-01-25T12:34:56.123456789Z"
  * Tradeoff: sorting by TEXT is chronological only if the format is stable.
  */
-export declare const temporalInstantIsoText: (name: string, opts?: {
+export declare const temporalInstantIsoText: (nameOrOpts?: string | {
+    Temporal?: TemporalRuntime;
+    precision?: ToStringPrecision;
+}, maybeOpts?: {
     Temporal?: TemporalRuntime;
     precision?: ToStringPrecision;
 }) => ReturnType<ReturnType<typeof customType<{
@@ -89,7 +115,10 @@ export declare const temporalInstantIsoText: (name: string, opts?: {
  * This is convenient, but if you need sorting/filtering by actual moment,
  * prefer the multi-column helper below (epochMs + timeZoneId + calendarId).
  */
-export declare const temporalZonedDateTimeText: (name: string, opts?: {
+export declare const temporalZonedDateTimeText: (nameOrOpts?: string | {
+    Temporal?: TemporalRuntime;
+    precision?: ToStringPrecision;
+}, maybeOpts?: {
     Temporal?: TemporalRuntime;
     precision?: ToStringPrecision;
 }) => ReturnType<ReturnType<typeof customType<{
@@ -114,4 +143,186 @@ export declare function unpackZonedDateTime(parts: {
 }, opts?: {
     Temporal?: TemporalRuntime;
 }): Temporal.ZonedDateTime;
+type StringKeyOf<T> = Extract<keyof T, string>;
+export type InstantPrefix<R> = {
+    [K in StringKeyOf<R>]: K extends `${infer P}EpochS` ? `${P}Nano` extends StringKeyOf<R> ? P : never : never;
+}[StringKeyOf<R>];
+export type ZonedDateTimeDualPrefix<R> = {
+    [K in StringKeyOf<R>]: K extends `${infer P}EpochS` ? `${P}Nano` extends StringKeyOf<R> ? `${P}TimeZoneId` extends StringKeyOf<R> ? `${P}Local` extends StringKeyOf<R> ? `${P}Offset` extends StringKeyOf<R> ? `${P}CalendarId` extends StringKeyOf<R> ? P : never : never : never : never : never : never;
+}[StringKeyOf<R>];
+export type UnpackFromRowOptions = {
+    Temporal?: TemporalRuntime;
+    /**
+     * When true, throws on missing/invalid values (recommended at the boundary).
+     * Defaults to true for unpack-from-row helpers.
+     */
+    validate?: boolean;
+    /**
+     * When true, additionally verifies that dual-write local/offset match what
+     * Temporal computes from (epoch, zone). This can fail across tzdb changes.
+     */
+    validateDualWriteLocalAndOffset?: boolean;
+    /**
+     * Used to canonicalize local/plain strings when validating dual-write fields.
+     * If not provided, uses the library defaults (nanosecond + trunc).
+     */
+    precision?: ToStringPrecision;
+};
+export declare const instantParts: <P extends string>(prefix: P, opts?: {
+    /**
+     * "explicit" (default): helpers choose DB column names (snake_case) unless overridden.
+     * "casing": omit DB column names and let Drizzle `casing` handle mapping.
+     */
+    mode?: "explicit" | "casing";
+    /** Overrides the derived DB prefix used in explicit mode. */
+    columnPrefix?: string;
+    /**
+     * Per-column DB name overrides (for existing schemas that don't match conventions).
+     * If provided for a column, it takes precedence over `mode`/`columnPrefix`.
+     */
+    columns?: Partial<{
+        epochS: string;
+        nano: string;
+    }>;
+}) => { [K in `${P}EpochS` | `${P}Nano`]: ReturnType<typeof integer>; };
+export declare const instantPartsNullable: <P extends string>(prefix: P, opts?: {
+    /**
+     * "explicit" (default): helpers choose DB column names (snake_case) unless overridden.
+     * "casing": omit DB column names and let Drizzle `casing` handle mapping.
+     */
+    mode?: "explicit" | "casing";
+    /** Overrides the derived DB prefix used in explicit mode. */
+    columnPrefix?: string;
+    /**
+     * Per-column DB name overrides (for existing schemas that don't match conventions).
+     * If provided for a column, it takes precedence over `mode`/`columnPrefix`.
+     */
+    columns?: Partial<{
+        epochS: string;
+        nano: string;
+    }>;
+}) => { [K in `${P}EpochS` | `${P}Nano`]: ReturnType<typeof integer>; };
+export declare function packInstantParts(instant: Temporal.Instant): {
+    epochS: number;
+    nano: number;
+};
+export declare function unpackInstantParts(parts: {
+    epochS: number;
+    nano: number;
+}, opts?: {
+    Temporal?: TemporalRuntime;
+}): Temporal.Instant;
+/**
+ * Pack helper (type-safe): constrains `prefix` to actual columns present on the table/row type.
+ * This catches typos like "ocurdAt" at compile-time.
+ */
+export declare const packInstant: <T extends object, P extends InstantPrefix<T>>(_tableOrRow: T, prefix: P, instant: Temporal.Instant) => { [K in `${P}EpochS` | `${P}Nano`]: number; };
+export declare const packInstantNullable: <T extends object, P extends InstantPrefix<T>>(_tableOrRow: T, prefix: P, instant: Temporal.Instant | null | undefined) => { [K in `${P}EpochS` | `${P}Nano`]: number | null; };
+type InstantKeyMap<R> = {
+    epochS: keyof R;
+    nano: keyof R;
+};
+export declare function unpackInstantFromRow<R extends Record<string, unknown>, P extends InstantPrefix<R>>(row: R, prefix: P, opts?: UnpackFromRowOptions): Temporal.Instant;
+export declare function unpackInstantFromRow<R extends Record<string, unknown>, M extends InstantKeyMap<R>>(row: R, map: M, opts?: UnpackFromRowOptions): Temporal.Instant;
+export declare function unpackInstantNullableFromRow<R extends Record<string, unknown>, P extends InstantPrefix<R>>(row: R, prefix: P, opts?: UnpackFromRowOptions): Temporal.Instant | null;
+export declare function unpackInstantNullableFromRow<R extends Record<string, unknown>, M extends InstantKeyMap<R>>(row: R, map: M, opts?: UnpackFromRowOptions): Temporal.Instant | null;
+export declare const zonedDateTimeDualParts: <P extends string>(prefix: P, opts?: {
+    /**
+     * "explicit" (default): helpers choose DB column names (snake_case) unless overridden.
+     * "casing": omit DB column names and let Drizzle `casing` handle mapping.
+     */
+    mode?: "explicit" | "casing";
+    /** Overrides the derived DB prefix used in explicit mode. */
+    columnPrefix?: string;
+    /**
+     * Per-column DB name overrides (for existing schemas that don't match conventions).
+     * If provided for a column, it takes precedence over `mode`/`columnPrefix`.
+     */
+    columns?: Partial<{
+        epochS: string;
+        nano: string;
+        timeZoneId: string;
+        local: string;
+        offset: string;
+        calendarId: string;
+    }>;
+}) => { [K in `${P}EpochS` | `${P}Nano` | `${P}TimeZoneId` | `${P}Local` | `${P}Offset` | `${P}CalendarId`]: K extends `${string}EpochS` | `${string}Nano` ? ReturnType<typeof integer> : ReturnType<typeof text>; };
+export declare const zonedDateTimeDualPartsNullable: <P extends string>(prefix: P, opts?: {
+    /**
+     * "explicit" (default): helpers choose DB column names (snake_case) unless overridden.
+     * "casing": omit DB column names and let Drizzle `casing` handle mapping.
+     */
+    mode?: "explicit" | "casing";
+    /** Overrides the derived DB prefix used in explicit mode. */
+    columnPrefix?: string;
+    /**
+     * Per-column DB name overrides (for existing schemas that don't match conventions).
+     * If provided for a column, it takes precedence over `mode`/`columnPrefix`.
+     */
+    columns?: Partial<{
+        epochS: string;
+        nano: string;
+        timeZoneId: string;
+        local: string;
+        offset: string;
+        calendarId: string;
+    }>;
+}) => { [K in `${P}EpochS` | `${P}Nano` | `${P}TimeZoneId` | `${P}Local` | `${P}Offset` | `${P}CalendarId`]: K extends `${string}EpochS` | `${string}Nano` ? ReturnType<typeof integer> : ReturnType<typeof text>; };
+export declare function packZonedDateTimeDualParts(zdt: Temporal.ZonedDateTime, opts?: {
+    precision?: ToStringPrecision;
+}): {
+    epochS: number;
+    nano: number;
+    timeZoneId: string;
+    local: string;
+    offset: string;
+    calendarId: string;
+};
+export declare function packZonedDateTimeDualNullableParts(zdt: Temporal.ZonedDateTime | null | undefined, opts?: {
+    precision?: ToStringPrecision;
+}): {
+    epochS: number;
+    nano: number;
+    timeZoneId: string;
+    local: string;
+    offset: string;
+    calendarId: string;
+} | {
+    epochS: null;
+    nano: null;
+    timeZoneId: null;
+    local: null;
+    offset: null;
+    calendarId: null;
+};
+export declare function unpackZonedDateTimeDualParts(parts: {
+    epochS: number;
+    nano: number;
+    timeZoneId: string;
+    local: string;
+    offset: string;
+    calendarId?: string;
+}, opts?: UnpackFromRowOptions): Temporal.ZonedDateTime;
+/**
+ * Safer pack helper: constrains `prefix` to actual columns present on the table/row type.
+ * This is the easiest way to catch typos like "starstAt" at compile-time.
+ */
+export declare const packZonedDateTimeDual: <T extends object, P extends ZonedDateTimeDualPrefix<T>>(_tableOrRow: T, prefix: P, zdt: Temporal.ZonedDateTime, opts?: {
+    precision?: ToStringPrecision;
+}) => { [K in `${P}EpochS` | `${P}Nano` | `${P}TimeZoneId` | `${P}Local` | `${P}Offset` | `${P}CalendarId`]: K extends `${string}EpochS` | `${string}Nano` ? number : string; };
+export declare const packZonedDateTimeDualNullable: <T extends object, P extends ZonedDateTimeDualPrefix<T>>(_tableOrRow: T, prefix: P, zdt: Temporal.ZonedDateTime | null | undefined, opts?: {
+    precision?: ToStringPrecision;
+}) => { [K in `${P}EpochS` | `${P}Nano` | `${P}TimeZoneId` | `${P}Local` | `${P}Offset` | `${P}CalendarId`]: K extends `${string}EpochS` | `${string}Nano` ? number | null : string | null; };
+type ZonedDateTimeDualKeyMap<R> = {
+    epochS: keyof R;
+    nano: keyof R;
+    timeZoneId: keyof R;
+    local: keyof R;
+    offset: keyof R;
+    calendarId?: keyof R;
+};
+export declare function unpackZonedDateTimeDualFromRow<R extends Record<string, unknown>, P extends ZonedDateTimeDualPrefix<R>>(row: R, prefix: P, opts?: UnpackFromRowOptions): Temporal.ZonedDateTime;
+export declare function unpackZonedDateTimeDualFromRow<R extends Record<string, unknown>, M extends ZonedDateTimeDualKeyMap<R>>(row: R, map: M, opts?: UnpackFromRowOptions): Temporal.ZonedDateTime;
+export declare function unpackZonedDateTimeDualNullableFromRow<R extends Record<string, unknown>, P extends ZonedDateTimeDualPrefix<R>>(row: R, prefix: P, opts?: UnpackFromRowOptions): Temporal.ZonedDateTime | null;
+export declare function unpackZonedDateTimeDualNullableFromRow<R extends Record<string, unknown>, M extends ZonedDateTimeDualKeyMap<R>>(row: R, map: M, opts?: UnpackFromRowOptions): Temporal.ZonedDateTime | null;
 export {};

package/dist/sqlite.js

@@ -1,12 +1,22 @@
+import { sql } from "drizzle-orm";
 import { customType, integer, text } from "drizzle-orm/sqlite-core";
 import "temporal-polyfill/global";
 function requireTemporal(runtime) {
     const T = runtime ?? globalThis.Temporal;
     if (!T) {
-        throw new Error("Temporal is not available at runtime. Pass { Temporal } from @js-temporal/polyfill or run in an environment with Temporal.");
+        throw new Error("Temporal is not available at runtime. Import temporal-polyfill/global (recommended) or pass { Temporal } from temporal-polyfill.");
     }
     return T;
 }
+function toSnakeCase(s) {
+    // Lightweight camelCase/PascalCase -> snake_case for DB column names.
+    // If users already pass snake_case, this is effectively a no-op.
+    return s
+        .replace(/-/g, "_")
+        .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+        .replace(/([A-Z]+)([A-Z][a-z0-9]+)/g, "$1_$2")
+        .toLowerCase();
+}
 /**
  * Stable fixed-width-ish defaults for DB persistence.
  * (Change smallestUnit to "millisecond" if you want shorter strings.)
@@ -15,92 +25,130 @@ const DEFAULT_PRECISION = {
     smallestUnit: "nanosecond",
     roundingMode: "trunc",
 };
+/**
+ * SQLite expression for "now" in epoch milliseconds.
+ *
+ * Uses strftime so we include milliseconds (not just whole seconds).
+ * Suitable for `.default(epochMsNow())` on INTEGER columns.
+ */
+export const epochMsNow = () => sql `CAST(strftime('%s','now') AS integer) * 1000 + CAST((strftime('%f','now') - strftime('%S','now')) * 1000 AS integer)`;
 /** PlainDate -> TEXT "YYYY-MM-DD" */
-export const temporalPlainDateText = (name, opts) => {
+export const temporalPlainDateText = (nameOrOpts, maybeOpts) => {
+    const name = typeof nameOrOpts === "string" ? nameOrOpts : undefined;
+    const opts = typeof nameOrOpts === "string" ? maybeOpts : nameOrOpts;
     const T = requireTemporal(opts?.Temporal);
-    return customType({
+    const col = customType({
         dataType: () => "text",
         toDriver: (v) => v.toString(),
         fromDriver: (v) => T.PlainDate.from(v),
-    })(name);
+        fromJson: (v) => T.PlainDate.from(v),
+    });
+    return name ? col(name) : col();
 };
 /** PlainTime -> TEXT "HH:mm:ss.sssssssss" (precision controlled via smallestUnit) */
-export const temporalPlainTimeText = (name, opts) => {
+export const temporalPlainTimeText = (nameOrOpts, maybeOpts) => {
+    const name = typeof nameOrOpts === "string" ? nameOrOpts : undefined;
+    const opts = typeof nameOrOpts === "string" ? maybeOpts : nameOrOpts;
     const T = requireTemporal(opts?.Temporal);
     const p = { ...DEFAULT_PRECISION, ...opts?.precision };
-    return customType({
+    const col = customType({
         dataType: () => "text",
         toDriver: (v) => v.toString(p),
         fromDriver: (v) => T.PlainTime.from(v),
-    })(name);
+        fromJson: (v) => T.PlainTime.from(v),
+    });
+    return name ? col(name) : col();
 };
 /** PlainDateTime -> TEXT "YYYY-MM-DDTHH:mm:ss.sssssssss" */
-export const temporalPlainDateTimeText = (name, opts) => {
+export const temporalPlainDateTimeText = (nameOrOpts, maybeOpts) => {
+    const name = typeof nameOrOpts === "string" ? nameOrOpts : undefined;
+    const opts = typeof nameOrOpts === "string" ? maybeOpts : nameOrOpts;
     const T = requireTemporal(opts?.Temporal);
     const p = { ...DEFAULT_PRECISION, ...opts?.precision };
-    return customType({
+    const col = customType({
         dataType: () => "text",
         toDriver: (v) => v.toString(p),
         fromDriver: (v) => T.PlainDateTime.from(v),
-    })(name);
+        fromJson: (v) => T.PlainDateTime.from(v),
+    });
+    return name ? col(name) : col();
 };
 /** PlainYearMonth -> TEXT "YYYY-MM" (plus optional calendar annotation if non-ISO) */
-export const temporalPlainYearMonthText = (name, opts) => {
+export const temporalPlainYearMonthText = (nameOrOpts, maybeOpts) => {
+    const name = typeof nameOrOpts === "string" ? nameOrOpts : undefined;
+    const opts = typeof nameOrOpts === "string" ? maybeOpts : nameOrOpts;
     const T = requireTemporal(opts?.Temporal);
-    return customType({
+    const col = customType({
         dataType: () => "text",
         toDriver: (v) => v.toString(),
         fromDriver: (v) => T.PlainYearMonth.from(v),
-    })(name);
+        fromJson: (v) => T.PlainYearMonth.from(v),
+    });
+    return name ? col(name) : col();
 };
 /** PlainMonthDay -> TEXT "MM-DD" (plus optional calendar annotation if non-ISO) */
-export const temporalPlainMonthDayText = (name, opts) => {
+export const temporalPlainMonthDayText = (nameOrOpts, maybeOpts) => {
+    const name = typeof nameOrOpts === "string" ? nameOrOpts : undefined;
+    const opts = typeof nameOrOpts === "string" ? maybeOpts : nameOrOpts;
     const T = requireTemporal(opts?.Temporal);
-    return customType({
+    const col = customType({
         dataType: () => "text",
         toDriver: (v) => v.toString(),
         fromDriver: (v) => T.PlainMonthDay.from(v),
-    })(name);
+        fromJson: (v) => T.PlainMonthDay.from(v),
+    });
+    return name ? col(name) : col();
 };
 /**
  * Duration -> TEXT ISO-8601, e.g. "PT15M", "P2DT3H"
  * Note: if millis/micros/nanos exceed 999, parsing back yields an
  * equal-but-differently-balanced Duration.
  */
-export const temporalDurationText = (name, opts) => {
+export const temporalDurationText = (nameOrOpts, maybeOpts) => {
+    const name = typeof nameOrOpts === "string" ? nameOrOpts : undefined;
+    const opts = typeof nameOrOpts === "string" ? maybeOpts : nameOrOpts;
     const T = requireTemporal(opts?.Temporal);
-    return customType({
+    const col = customType({
         dataType: () => "text",
         toDriver: (v) => v.toString(),
         fromDriver: (v) => T.Duration.from(v),
-    })(name);
+        fromJson: (v) => T.Duration.from(v),
+    });
+    return name ? col(name) : col();
 };
 /**
  * Instant (recommended) -> INTEGER epoch milliseconds
  * Great for sorting/filtering by actual time.
  * Tradeoff: millisecond precision only.
  */
-export const temporalInstantEpochMs = (name, opts) => {
+export const temporalInstantEpochMs = (nameOrOpts, maybeOpts) => {
+    const name = typeof nameOrOpts === "string" ? nameOrOpts : undefined;
+    const opts = typeof nameOrOpts === "string" ? maybeOpts : nameOrOpts;
     const T = requireTemporal(opts?.Temporal);
-    return customType({
+    const col = customType({
         dataType: () => "integer",
         toDriver: (v) => v.epochMilliseconds,
         fromDriver: (v) => T.Instant.fromEpochMilliseconds(typeof v === "string" ? Number(v) : v),
         fromJson: (v) => T.Instant.fromEpochMilliseconds(typeof v === "string" ? Number(v) : v),
-    })(name);
+    });
+    return name ? col(name) : col();
 };
 /**
  * Instant (lossless) -> TEXT ISO string, e.g. "2026-01-25T12:34:56.123456789Z"
  * Tradeoff: sorting by TEXT is chronological only if the format is stable.
  */
-export const temporalInstantIsoText = (name, opts) => {
+export const temporalInstantIsoText = (nameOrOpts, maybeOpts) => {
+    const name = typeof nameOrOpts === "string" ? nameOrOpts : undefined;
+    const opts = typeof nameOrOpts === "string" ? maybeOpts : nameOrOpts;
     const T = requireTemporal(opts?.Temporal);
     const p = { ...DEFAULT_PRECISION, ...opts?.precision };
-    return customType({
+    const col = customType({
         dataType: () => "text",
         toDriver: (v) => v.toString(p),
         fromDriver: (v) => T.Instant.from(v),
-    })(name);
+        fromJson: (v) => T.Instant.from(v),
+    });
+    return name ? col(name) : col();
 };
 /**
  * ZonedDateTime (single-column) -> TEXT with zone annotation.
@@ -109,14 +157,18 @@ export const temporalInstantIsoText = (name, opts) => {
  * This is convenient, but if you need sorting/filtering by actual moment,
  * prefer the multi-column helper below (epochMs + timeZoneId + calendarId).
  */
-export const temporalZonedDateTimeText = (name, opts) => {
+export const temporalZonedDateTimeText = (nameOrOpts, maybeOpts) => {
+    const name = typeof nameOrOpts === "string" ? nameOrOpts : undefined;
+    const opts = typeof nameOrOpts === "string" ? maybeOpts : nameOrOpts;
     const T = requireTemporal(opts?.Temporal);
     const p = { ...DEFAULT_PRECISION, ...opts?.precision };
-    return customType({
+    const col = customType({
         dataType: () => "text",
         toDriver: (v) => v.toString({ ...p, timeZoneName: "auto" }),
         fromDriver: (v) => T.ZonedDateTime.from(v),
-    })(name);
+        fromJson: (v) => T.ZonedDateTime.from(v),
+    });
+    return name ? col(name) : col();
 };
 /* ------------------------------------------------------------------------------------------------
  * Multi-column (“flattened”) helpers
@@ -140,3 +192,343 @@ export function unpackZonedDateTime(parts, opts) {
     const zdt = T.Instant.fromEpochMilliseconds(parts.epochMs).toZonedDateTimeISO(parts.timeZoneId);
     return parts.calendarId ? zdt.withCalendar(parts.calendarId) : zdt;
 }
+const NS_PER_S = 1000000000n;
+function joinEpochNs(epochS, nano) {
+    return BigInt(epochS) * NS_PER_S + BigInt(nano);
+}
+function splitEpochNs(epochNs) {
+    // Keep nano in [0..999,999,999] even for negative instants.
+    let s = epochNs / NS_PER_S;
+    let n = epochNs % NS_PER_S;
+    if (n < 0n) {
+        s -= 1n;
+        n += NS_PER_S;
+    }
+    const epochS = Number(s);
+    if (!Number.isSafeInteger(epochS)) {
+        throw new Error("Instant is outside the safe integer range for epoch seconds. Use a bigint-based representation instead.");
+    }
+    return { epochS, nano: Number(n) };
+}
+export const instantParts = (prefix, opts) => {
+    const out = {};
+    const epochSName = opts?.columns?.epochS ??
+        (opts?.mode === "casing"
+            ? undefined
+            : `${(opts?.columnPrefix ?? toSnakeCase(prefix))}_epoch_s`);
+    const nanoName = opts?.columns?.nano ??
+        (opts?.mode === "casing"
+            ? undefined
+            : `${(opts?.columnPrefix ?? toSnakeCase(prefix))}_nano`);
+    out[`${prefix}EpochS`] = (epochSName
+        ? integer(epochSName)
+        : integer()).notNull();
+    out[`${prefix}Nano`] = (nanoName ? integer(nanoName) : integer()).notNull();
+    return out;
+};
+export const instantPartsNullable = (prefix, opts) => {
+    const out = {};
+    const epochSName = opts?.columns?.epochS ??
+        (opts?.mode === "casing"
+            ? undefined
+            : `${(opts?.columnPrefix ?? toSnakeCase(prefix))}_epoch_s`);
+    const nanoName = opts?.columns?.nano ??
+        (opts?.mode === "casing"
+            ? undefined
+            : `${(opts?.columnPrefix ?? toSnakeCase(prefix))}_nano`);
+    // Nullable columns: we enforce "all-or-none" in unpack helpers.
+    out[`${prefix}EpochS`] = epochSName
+        ? integer(epochSName)
+        : integer();
+    out[`${prefix}Nano`] = nanoName ? integer(nanoName) : integer();
+    return out;
+};
+export function packInstantParts(instant) {
+    const { epochS, nano } = splitEpochNs(instant.epochNanoseconds);
+    return { epochS, nano };
+}
+export function unpackInstantParts(parts, opts) {
+    const T = requireTemporal(opts?.Temporal);
+    return T.Instant.fromEpochNanoseconds(joinEpochNs(parts.epochS, parts.nano));
+}
+/**
+ * Pack helper (type-safe): constrains `prefix` to actual columns present on the table/row type.
+ * This catches typos like "ocurdAt" at compile-time.
+ */
+export const packInstant = (_tableOrRow, prefix, instant) => {
+    const { epochS, nano } = packInstantParts(instant);
+    const out = {};
+    out[`${prefix}EpochS`] = epochS;
+    out[`${prefix}Nano`] = nano;
+    return out;
+};
+export const packInstantNullable = (_tableOrRow, prefix, instant) => {
+    const out = {};
+    if (instant == null) {
+        out[`${prefix}EpochS`] = null;
+        out[`${prefix}Nano`] = null;
+        return out;
+    }
+    const { epochS, nano } = packInstantParts(instant);
+    out[`${prefix}EpochS`] = epochS;
+    out[`${prefix}Nano`] = nano;
+    return out;
+};
+export function unpackInstantFromRow(row, prefixOrMap, opts) {
+    const validate = opts?.validate ?? true;
+    const map = typeof prefixOrMap === "string"
+        ? { epochS: `${prefixOrMap}EpochS`, nano: `${prefixOrMap}Nano` }
+        : { epochS: String(prefixOrMap.epochS), nano: String(prefixOrMap.nano) };
+    const epochRaw = row[map.epochS];
+    const nanoRaw = row[map.nano];
+    const epochS = typeof epochRaw === "string" ? Number(epochRaw) : epochRaw;
+    const nano = typeof nanoRaw === "string" ? Number(nanoRaw) : nanoRaw;
+    if (validate) {
+        if (!Number.isSafeInteger(epochS))
+            throw new Error("Invalid epochS");
+        if (!Number.isInteger(nano) || nano < 0 || nano > 999_999_999) {
+            throw new Error("Invalid nano");
+        }
+    }
+    return unpackInstantParts({ epochS, nano }, { Temporal: opts?.Temporal });
+}
+export function unpackInstantNullableFromRow(row, prefixOrMap, opts) {
+    const validate = opts?.validate ?? true;
+    const map = typeof prefixOrMap === "string"
+        ? { epochS: `${prefixOrMap}EpochS`, nano: `${prefixOrMap}Nano` }
+        : { epochS: String(prefixOrMap.epochS), nano: String(prefixOrMap.nano) };
+    const epochRaw = row[map.epochS];
+    const nanoRaw = row[map.nano];
+    const epochIsNull = epochRaw == null;
+    const nanoIsNull = nanoRaw == null;
+    if (epochIsNull && nanoIsNull)
+        return null;
+    if (validate && epochIsNull !== nanoIsNull) {
+        throw new Error("Nullable Instant parts must be all-null or all-set");
+    }
+    const epochS = typeof epochRaw === "string" ? Number(epochRaw) : epochRaw;
+    const nano = typeof nanoRaw === "string" ? Number(nanoRaw) : nanoRaw;
+    if (validate) {
+        if (!Number.isSafeInteger(epochS))
+            throw new Error("Invalid epochS");
+        if (!Number.isInteger(nano) || nano < 0 || nano > 999_999_999) {
+            throw new Error("Invalid nano");
+        }
+    }
+    return unpackInstantParts({ epochS, nano }, { Temporal: opts?.Temporal });
+}
+export const zonedDateTimeDualParts = (prefix, opts) => {
+    const out = {};
+    const colPrefix = opts?.mode === "casing" ? undefined : (opts?.columnPrefix ?? toSnakeCase(prefix));
+    const epochSName = opts?.columns?.epochS ?? (colPrefix ? `${colPrefix}_epoch_s` : undefined);
+    const nanoName = opts?.columns?.nano ?? (colPrefix ? `${colPrefix}_nano` : undefined);
+    const timeZoneIdName = opts?.columns?.timeZoneId ?? (colPrefix ? `${colPrefix}_tz` : undefined);
+    const localName = opts?.columns?.local ?? (colPrefix ? `${colPrefix}_local` : undefined);
+    const offsetName = opts?.columns?.offset ?? (colPrefix ? `${colPrefix}_offset` : undefined);
+    const calendarIdName = opts?.columns?.calendarId ?? (colPrefix ? `${colPrefix}_cal` : undefined);
+    out[`${prefix}EpochS`] = (epochSName ? integer(epochSName) : integer()).notNull();
+    out[`${prefix}Nano`] = (nanoName ? integer(nanoName) : integer()).notNull();
+    out[`${prefix}TimeZoneId`] = (timeZoneIdName ? text(timeZoneIdName) : text()).notNull();
+    out[`${prefix}Local`] = (localName ? text(localName) : text()).notNull();
+    out[`${prefix}Offset`] = (offsetName ? text(offsetName) : text()).notNull();
+    out[`${prefix}CalendarId`] = (calendarIdName ? text(calendarIdName) : text())
+        .notNull()
+        .default("iso8601");
+    return out;
+};
+export const zonedDateTimeDualPartsNullable = (prefix, opts) => {
+    const out = {};
+    const colPrefix = opts?.mode === "casing" ? undefined : (opts?.columnPrefix ?? toSnakeCase(prefix));
+    const epochSName = opts?.columns?.epochS ?? (colPrefix ? `${colPrefix}_epoch_s` : undefined);
+    const nanoName = opts?.columns?.nano ?? (colPrefix ? `${colPrefix}_nano` : undefined);
+    const timeZoneIdName = opts?.columns?.timeZoneId ?? (colPrefix ? `${colPrefix}_tz` : undefined);
+    const localName = opts?.columns?.local ?? (colPrefix ? `${colPrefix}_local` : undefined);
+    const offsetName = opts?.columns?.offset ?? (colPrefix ? `${colPrefix}_offset` : undefined);
+    const calendarIdName = opts?.columns?.calendarId ?? (colPrefix ? `${colPrefix}_cal` : undefined);
+    // Nullable columns: no defaults, and unpack helpers enforce "all-or-none".
+    out[`${prefix}EpochS`] = (epochSName ? integer(epochSName) : integer());
+    out[`${prefix}Nano`] = (nanoName ? integer(nanoName) : integer());
+    out[`${prefix}TimeZoneId`] = (timeZoneIdName ? text(timeZoneIdName) : text());
+    out[`${prefix}Local`] = (localName ? text(localName) : text());
+    out[`${prefix}Offset`] = (offsetName ? text(offsetName) : text());
+    out[`${prefix}CalendarId`] = (calendarIdName ? text(calendarIdName) : text());
+    return out;
+};
+export function packZonedDateTimeDualParts(zdt, opts) {
+    const { epochS, nano } = splitEpochNs(zdt.epochNanoseconds);
+    const p = { ...DEFAULT_PRECISION, ...opts?.precision };
+    return {
+        epochS,
+        nano,
+        timeZoneId: zdt.timeZoneId,
+        local: zdt.toPlainDateTime().toString(p),
+        offset: zdt.offset,
+        calendarId: zdt.calendarId,
+    };
+}
+export function packZonedDateTimeDualNullableParts(zdt, opts) {
+    if (zdt == null) {
+        return {
+            epochS: null,
+            nano: null,
+            timeZoneId: null,
+            local: null,
+            offset: null,
+            calendarId: null,
+        };
+    }
+    return packZonedDateTimeDualParts(zdt, opts);
+}
+export function unpackZonedDateTimeDualParts(parts, opts) {
+    const T = requireTemporal(opts?.Temporal);
+    const instant = T.Instant.fromEpochNanoseconds(joinEpochNs(parts.epochS, parts.nano));
+    const zdt = instant.toZonedDateTimeISO(parts.timeZoneId);
+    const zdtWithCal = parts.calendarId ? zdt.withCalendar(parts.calendarId) : zdt;
+    const validate = opts?.validate ?? true;
+    if (validate && opts?.validateDualWriteLocalAndOffset) {
+        const p = { ...DEFAULT_PRECISION, ...opts?.precision };
+        const expectedLocal = zdtWithCal.toPlainDateTime().toString(p);
+        const expectedOffset = zdtWithCal.offset;
+        if (expectedLocal !== parts.local)
+            throw new Error("Dual-write local does not match");
+        if (expectedOffset !== parts.offset)
+            throw new Error("Dual-write offset does not match");
+    }
+    return zdtWithCal;
+}
+/**
+ * Safer pack helper: constrains `prefix` to actual columns present on the table/row type.
+ * This is the easiest way to catch typos like "starstAt" at compile-time.
+ */
+export const packZonedDateTimeDual = (_tableOrRow, prefix, zdt, opts) => {
+    // Delegate to parts + typed prefix keys.
+    const parts = packZonedDateTimeDualParts(zdt, opts);
+    const out = {};
+    out[`${prefix}EpochS`] = parts.epochS;
+    out[`${prefix}Nano`] = parts.nano;
+    out[`${prefix}TimeZoneId`] = parts.timeZoneId;
+    out[`${prefix}Local`] = parts.local;
+    out[`${prefix}Offset`] = parts.offset;
+    out[`${prefix}CalendarId`] = parts.calendarId;
+    return out;
+};
+export const packZonedDateTimeDualNullable = (_tableOrRow, prefix, zdt, opts) => {
+    const parts = packZonedDateTimeDualNullableParts(zdt, opts);
+    const out = {};
+    out[`${prefix}EpochS`] = parts.epochS;
+    out[`${prefix}Nano`] = parts.nano;
+    out[`${prefix}TimeZoneId`] = parts.timeZoneId;
+    out[`${prefix}Local`] = parts.local;
+    out[`${prefix}Offset`] = parts.offset;
+    out[`${prefix}CalendarId`] = parts.calendarId;
+    return out;
+};
+export function unpackZonedDateTimeDualFromRow(row, prefixOrMap, opts) {
+    const validate = opts?.validate ?? true;
+    const map = typeof prefixOrMap === "string"
+        ? {
+            epochS: `${prefixOrMap}EpochS`,
+            nano: `${prefixOrMap}Nano`,
+            timeZoneId: `${prefixOrMap}TimeZoneId`,
+            local: `${prefixOrMap}Local`,
+            offset: `${prefixOrMap}Offset`,
+            calendarId: `${prefixOrMap}CalendarId`,
+        }
+        : {
+            epochS: String(prefixOrMap.epochS),
+            nano: String(prefixOrMap.nano),
+            timeZoneId: String(prefixOrMap.timeZoneId),
+            local: String(prefixOrMap.local),
+            offset: String(prefixOrMap.offset),
+            calendarId: prefixOrMap.calendarId ? String(prefixOrMap.calendarId) : undefined,
+        };
+    const epochRaw = row[map.epochS];
+    const nanoRaw = row[map.nano];
+    const epochS = typeof epochRaw === "string" ? Number(epochRaw) : epochRaw;
+    const nano = typeof nanoRaw === "string" ? Number(nanoRaw) : nanoRaw;
+    const timeZoneId = row[map.timeZoneId];
+    const local = row[map.local];
+    const offset = row[map.offset];
+    const calendarId = map.calendarId ? row[map.calendarId] : undefined;
+    if (validate) {
+        if (!Number.isSafeInteger(epochS))
+            throw new Error("Invalid epochS");
+        if (!Number.isInteger(nano) || nano < 0 || nano > 999_999_999) {
+            throw new Error("Invalid nano");
+        }
+        if (typeof timeZoneId !== "string" || !timeZoneId)
+            throw new Error("Invalid timeZoneId");
+        if (typeof local !== "string" || !local)
+            throw new Error("Invalid local");
+        if (typeof offset !== "string" || !offset)
+            throw new Error("Invalid offset");
+        if (calendarId != null && typeof calendarId !== "string")
+            throw new Error("Invalid calendarId");
+    }
+    return unpackZonedDateTimeDualParts({ epochS, nano, timeZoneId, local, offset, calendarId }, opts);
+}
+export function unpackZonedDateTimeDualNullableFromRow(row, prefixOrMap, opts) {
+    const validate = opts?.validate ?? true;
+    const map = typeof prefixOrMap === "string"
+        ? {
+            epochS: `${prefixOrMap}EpochS`,
+            nano: `${prefixOrMap}Nano`,
+            timeZoneId: `${prefixOrMap}TimeZoneId`,
+            local: `${prefixOrMap}Local`,
+            offset: `${prefixOrMap}Offset`,
+            calendarId: `${prefixOrMap}CalendarId`,
+        }
+        : {
+            epochS: String(prefixOrMap.epochS),
+            nano: String(prefixOrMap.nano),
+            timeZoneId: String(prefixOrMap.timeZoneId),
+            local: String(prefixOrMap.local),
+            offset: String(prefixOrMap.offset),
+            calendarId: prefixOrMap.calendarId ? String(prefixOrMap.calendarId) : undefined,
+        };
+    const epochRaw = row[map.epochS];
+    const nanoRaw = row[map.nano];
+    const timeZoneIdRaw = row[map.timeZoneId];
+    const localRaw = row[map.local];
+    const offsetRaw = row[map.offset];
+    const calendarIdRaw = map.calendarId ? row[map.calendarId] : undefined;
+    const allNull = epochRaw == null &&
+        nanoRaw == null &&
+        timeZoneIdRaw == null &&
+        localRaw == null &&
+        offsetRaw == null &&
+        calendarIdRaw == null;
+    if (allNull)
+        return null;
+    if (validate &&
+        (epochRaw == null ||
+            nanoRaw == null ||
+            timeZoneIdRaw == null ||
+            localRaw == null ||
+            offsetRaw == null ||
+            calendarIdRaw == null)) {
+        throw new Error("Nullable ZonedDateTime parts must be all-null or all-set");
+    }
+    const epochS = typeof epochRaw === "string" ? Number(epochRaw) : epochRaw;
+    const nano = typeof nanoRaw === "string" ? Number(nanoRaw) : nanoRaw;
+    const timeZoneId = timeZoneIdRaw;
+    const local = localRaw;
+    const offset = offsetRaw;
+    const calendarId = calendarIdRaw;
+    if (validate) {
+        if (!Number.isSafeInteger(epochS))
+            throw new Error("Invalid epochS");
+        if (!Number.isInteger(nano) || nano < 0 || nano > 999_999_999) {
+            throw new Error("Invalid nano");
+        }
+        if (typeof timeZoneId !== "string" || !timeZoneId)
+            throw new Error("Invalid timeZoneId");
+        if (typeof local !== "string" || !local)
+            throw new Error("Invalid local");
+        if (typeof offset !== "string" || !offset)
+            throw new Error("Invalid offset");
+        if (typeof calendarId !== "string" || !calendarId)
+            throw new Error("Invalid calendarId");
+    }
+    return unpackZonedDateTimeDualParts({ epochS, nano, timeZoneId, local, offset, calendarId }, opts);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sedrino/drizzle",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "main": "./dist/sqlite.js",
   "types": "./dist/sqlite.d.ts",
   "exports": {
@@ -19,9 +19,13 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@libsql/client": "^0.15.0",
     "typescript": "^5.6.3"
   },
   "scripts": {
-    "build": "bunx tsc -p tsconfig.build.json"
+    "build": "bunx tsc -p tsconfig.build.json",
+    "test": "bun test",
+    "test:types": "bunx tsc -p tsconfig.types.json",
+    "test:all": "bun test && bunx tsc -p tsconfig.types.json"
   }
 }