turbine-orm 0.25.0 → 0.26.0

package/dist/query/index.d.ts

@@ -5,7 +5,7 @@
  * `import { … } from './query/index.js'` is a drop-in replacement for the
  * former monolithic `import { … } from './query.js'`.
  */
-export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, HavingClause, JsonFilter, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, SelectResult, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
+export type { AggregateArgs, AggregateResult, ArrayFilter, ConnectOrCreateOp, CountArgs, CreateArgs, CreateDataInput, CreateManyArgs, DeleteArgs, DeleteManyArgs, FieldResult, FindManyArgs, FindManyStreamArgs, FindUniqueArgs, GroupByArgs, HavingClause, JsonFilter, NestedCreateOp, NestedUpdateOp, NestedUpdateOpItem, NestedUpsertOpItem, OmitResult, OrderByClause, OrderDirection, QueryResult, RelationDescriptor, RelationFilter, RelationLoadStrategy, SelectResult, TextSearchFilter, TypedWithClause, UpdateArgs, UpdateDataInput, UpdateInput, UpdateManyArgs, UpdateOperatorInput, UpsertArgs, VectorDistanceFilter, VectorFilter, VectorMetric, VectorOrderBy, VectorOrderByDistance, WhereClause, WhereOperator, WhereValue, WithClause, WithOptions, WithResult, } from './types.js';
 export type { BuiltStatement, BulkInsertStatementInput, ColumnDefinitionInput, ColumnTypeInput, CreateIndexStatementInput, CreateTableStatementInput, Dialect, InsertStatementInput, UpsertStatementInput, } from '../dialect.js';
 export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';

package/dist/query/types.d.ts

@@ -4,6 +4,20 @@
  * All exported type and interface definitions for the query builder module.
  */
 export type OrderDirection = 'asc' | 'desc';
+/**
+ * How a query resolves its `with` relations.
+ *
+ *   - `'join'` (default) — one SQL statement with correlated
+ *     `json_agg(json_build_object(...))` subqueries. One round-trip; an index
+ *     seek per parent row when the child FK is indexed.
+ *   - `'batched'` — run the base query, then ONE flat follow-up query per
+ *     relation (`WHERE fk = ANY($1)`), stitching children client-side. D levels
+ *     cost D extra round-trips, but each is a single key-set lookup and rows come
+ *     back flat — a win when FK columns are unindexed or result sets are huge.
+ *
+ * Precedence: per-query arg > client `relationLoadStrategy` config > `'join'`.
+ */
+export type RelationLoadStrategy = 'join' | 'batched';
 /** Operator object for advanced where filtering */
 export interface WhereOperator<V = unknown> {
     /**
@@ -36,7 +50,21 @@ export interface WhereOperator<V = unknown> {
  * - A text search filter object ({ search, config? })
  * - A vector distance filter object ({ distance: { to, metric, lt } }) for pgvector columns
  */
-export type WhereValue<V = unknown> = V | WhereOperator<V> | JsonFilter | ArrayFilter | TextSearchFilter | VectorFilter | null;
+export type WhereValue<V = unknown> = (V extends Array<infer U> ? TypedRelationFilter<U> : V extends Date ? V : V extends object ? V | TypedToOneFilter<V> | WhereClause<V> : V) | WhereOperator<V> | JsonFilter | ArrayFilter | TextSearchFilter | VectorFilter | null;
+/** Relation filter on a to-many relation property. */
+export interface TypedRelationFilter<U> {
+    some?: WhereClause<U>;
+    every?: WhereClause<U>;
+    none?: WhereClause<U>;
+}
+/**
+ * Relation filter on a to-one relation property. A bare object on a to-one
+ * relation key is also accepted at runtime (implicit `is`, Prisma-compatible).
+ */
+export interface TypedToOneFilter<V> {
+    is?: WhereClause<V>;
+    isNot?: WhereClause<V>;
+}
 /**
  * Where clause type: each field can be a plain value, null, or operator object.
  * Special keys: OR for disjunctive conditions.
@@ -192,7 +220,7 @@ export type FieldResult<T, S extends Record<string, boolean> | undefined, O exte
  * Short-circuits to plain WithResult when neither select nor omit is provided,
  * preserving exact type equality with the pre-narrowing era.
  */
-export type QueryResult<T, R extends object, W, S extends Record<string, boolean> | undefined, O extends Record<string, boolean> | undefined> = S extends undefined ? O extends undefined ? WithResult<T, R, W> : O extends Record<string, boolean> ? Omit<WithResult<T, R, W>, Extract<keyof T, TrueKeys<O>>> : WithResult<T, R, W> : S extends Record<string, boolean> ? Pick<WithResult<T, R, W>, Extract<keyof T, TrueKeys<S>> | Exclude<keyof WithResult<T, R, W>, keyof T>> : WithResult<T, R, W>;
+export type QueryResult<T, R extends object, W, S extends Record<string, boolean> | undefined, O extends Record<string, boolean> | undefined> = S extends undefined ? O extends undefined ? WithResult<T, R, W> : O extends Record<string, boolean> ? Omit<WithResult<T, R, W>, Exclude<Extract<keyof T, TrueKeys<O>>, keyof W>> : WithResult<T, R, W> : S extends Record<string, boolean> ? Pick<WithResult<T, R, W>, Extract<keyof T, TrueKeys<S>> | Exclude<keyof WithResult<T, R, W>, keyof T> | Extract<keyof W, keyof WithResult<T, R, W>>> : WithResult<T, R, W>;
 export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
     where: WhereClause<T>;
     select?: S;
@@ -200,6 +228,8 @@ export interface FindUniqueArgs<T, R extends object = {}, W extends TypedWithCla
     with?: W;
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** Override the client's relation-loading strategy for this query. See {@link RelationLoadStrategy}. */
+    relationLoadStrategy?: RelationLoadStrategy;
 }
 export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> {
     where?: WhereClause<T>;
@@ -217,6 +247,8 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
     distinct?: (keyof T & string)[];
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */
     timeout?: number;
+    /** Override the client's relation-loading strategy for this query. See {@link RelationLoadStrategy}. */
+    relationLoadStrategy?: RelationLoadStrategy;
 }
 export interface FindManyStreamArgs<T, R extends object = {}, W extends TypedWithClause<R> = TypedWithClause<R>, S extends Record<string, boolean> | undefined = undefined, O extends Record<string, boolean> | undefined = undefined> extends FindManyArgs<T, R, W, S, O> {
     /**
@@ -505,6 +537,9 @@ export interface RelationFilter {
     some?: Record<string, unknown>;
     every?: Record<string, unknown>;
     none?: Record<string, unknown>;
+    /** To-one relation match (bare objects on to-one keys are implicit `is`). */
+    is?: Record<string, unknown>;
+    isNot?: Record<string, unknown>;
 }
 /** JSONB query operators for where clauses */
 export interface JsonFilter {

package/dist/query/utils.d.ts

@@ -65,3 +65,19 @@ export declare const OPERATOR_KEYS: Set<string>;
  * For multi-column:  `"alias"."col_a" = "parent"."ref_a" AND "alias"."col_b" = "parent"."ref_b"`
  */
 export declare function buildCorrelation(leftRef: string, leftColumns: string | string[], rightRef: string, rightColumns: string | string[]): string;
+/**
+ * Parse a database date-time string deterministically.
+ *
+ * Postgres `timestamp` (without time zone) values arrive with no offset —
+ * both from the driver and from `json_agg`/`json_build_object` subquery JSON
+ * (`2026-07-07T17:15:41.896`). JavaScript's `new Date()` interprets such
+ * strings in the SERVER'S LOCAL TIME ZONE, so the same row parses to a
+ * different instant depending on where the code runs. The universal ORM
+ * convention (Prisma, Rails, Django) is to treat offset-less timestamps as
+ * UTC — that is also the only interpretation that round-trips: Postgres
+ * stores exactly the wall-clock fields you sent.
+ *
+ * Strings that carry an explicit offset (`timestamptz` output) are parsed
+ * as-is.
+ */
+export declare function parseDbDate(value: string): Date;

package/dist/query/utils.js

@@ -129,3 +129,38 @@ export function buildCorrelation(leftRef, leftColumns, rightRef, rightColumns) {
         .map((col, i) => `${leftRef}.${quoteIdent(col)} = ${rightRef}.${quoteIdent(rightCols[i])}`)
         .join(' AND ');
 }
+/**
+ * Matches an explicit timezone suffix on a date-time string: a trailing `Z`
+ * or a `±HH`, `±HHMM`, `±HH:MM` offset.
+ */
+const TZ_SUFFIX_RE = /(?:Z|[+-]\d{2}(?::?\d{2})?)$/;
+/**
+ * Parse a database date-time string deterministically.
+ *
+ * Postgres `timestamp` (without time zone) values arrive with no offset —
+ * both from the driver and from `json_agg`/`json_build_object` subquery JSON
+ * (`2026-07-07T17:15:41.896`). JavaScript's `new Date()` interprets such
+ * strings in the SERVER'S LOCAL TIME ZONE, so the same row parses to a
+ * different instant depending on where the code runs. The universal ORM
+ * convention (Prisma, Rails, Django) is to treat offset-less timestamps as
+ * UTC — that is also the only interpretation that round-trips: Postgres
+ * stores exactly the wall-clock fields you sent.
+ *
+ * Strings that carry an explicit offset (`timestamptz` output) are parsed
+ * as-is.
+ */
+export function parseDbDate(value) {
+    // Date-only values (`2026-07-07`, from `date` columns in json_agg output)
+    // have no time to zone-pin — and their `-07` tail must not be read as an
+    // offset. JS parses bare ISO dates as UTC midnight already.
+    if (!value.includes(':'))
+        return new Date(value);
+    if (TZ_SUFFIX_RE.test(value)) {
+        // JS Date can't parse colon-less (`-0430`) or bare-hour (`+02`) offsets —
+        // normalize both to `±HH:MM`. Postgres emits the bare-hour form for
+        // whole-hour zones in some text outputs.
+        return new Date(value.replace(/([+-]\d{2})(\d{2})$/, '$1:$2').replace(/([+-]\d{2})$/, '$1:00'));
+    }
+    // normalize `YYYY-MM-DD HH:MM:SS` (driver form) to ISO before pinning UTC
+    return new Date(`${value.replace(' ', 'T')}Z`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbine-orm",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Postgres-native TypeScript ORM — runs on Neon, Vercel Postgres, Cloudflare, Supabase. Streaming cursors, typed errors, single-query nested relations. One dependency, no WASM engine",
   "type": "module",
   "exports": {