turbine-orm 0.32.0 → 0.32.2

package/dist/errors.js

@@ -144,8 +144,16 @@ export class NotFoundError extends TurbineError {
 /** Thrown when a query or transaction exceeds the configured timeout */
 export class TimeoutError extends TurbineError {
     timeoutMs;
-    constructor(timeoutMs, context = 'Query') {
-        super(TurbineErrorCode.TIMEOUT, `[turbine] ${context} timed out after ${timeoutMs}ms`);
+    /**
+     * @param timeoutMs the client-side timeout budget in ms. Pass `0` when the
+     *   duration is unknown (e.g. a server-side `statement_timeout` cancellation
+     *   surfaced via `wrapPgError`, where Turbine did not set the deadline).
+     * @param context human label for the operation ("Query", "Transaction").
+     * @param options optional `message` override and pg `cause` to preserve, used
+     *   when wrapping a driver error rather than a client-side timer expiry.
+     */
+    constructor(timeoutMs, context = 'Query', options) {
+        super(TurbineErrorCode.TIMEOUT, options?.message ?? `[turbine] ${context} timed out after ${timeoutMs}ms`, options);
         this.name = 'TimeoutError';
         this.timeoutMs = timeoutMs;
     }
@@ -159,8 +167,13 @@ export class ValidationError extends TurbineError {
 }
 /** Thrown when a database connection fails */
 export class ConnectionError extends TurbineError {
-    constructor(message) {
-        super(TurbineErrorCode.CONNECTION, message);
+    /**
+     * @param message human-readable connection failure description.
+     * @param options optional pg/driver `cause` to preserve, used when wrapping a
+     *   connection-class driver error via `wrapPgError`.
+     */
+    constructor(message, options) {
+        super(TurbineErrorCode.CONNECTION, message, options);
         this.name = 'ConnectionError';
     }
 }
@@ -477,6 +490,35 @@ function parseColumnsFromDetail(detail) {
         return undefined;
     return m[1].split(',').map((s) => s.trim());
 }
+/**
+ * Connection-class error codes. Covers both pg SQLSTATEs (class 08
+ * connection_exception, plus a few class-53/57 admin/availability codes) and
+ * Node driver-level error codes that arrive on the same `.code` field when the
+ * socket never reaches Postgres. All map to {@link ConnectionError} (E004).
+ *
+ * `57014` (query_canceled, a server-side `statement_timeout` cancellation) is
+ * intentionally NOT here: it maps to {@link TimeoutError} (E002) instead.
+ */
+const CONNECTION_ERROR_CODES = new Set([
+    // pg SQLSTATE class 08: connection_exception
+    '08000', // connection_exception
+    '08001', // sqlclient_unable_to_establish_sqlconnection
+    '08003', // connection_does_not_exist
+    '08004', // sqlserver_rejected_establishment_of_sqlconnection
+    '08006', // connection_failure
+    '08P01', // protocol_violation
+    // pg SQLSTATE class 53/57 (server unavailable / shutting down)
+    '53300', // too_many_connections
+    '57P01', // admin_shutdown
+    '57P02', // crash_shutdown
+    '57P03', // cannot_connect_now
+    // Node driver-level socket errors (surface on err.code too)
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'ENOTFOUND',
+    'EPIPE',
+]);
 /**
  * Translate a pg driver error into a typed Turbine error.
  * If the error doesn't match a known constraint code, returns it unchanged.
@@ -489,6 +531,8 @@ function parseColumnsFromDetail(detail) {
  *   23P01 (exclusion_violation)   -> ExclusionConstraintError
  *   40P01 (deadlock_detected)     -> DeadlockError       (retryable)
  *   40001 (serialization_failure) -> SerializationFailureError (retryable)
+ *   57014 (query_canceled)        -> TimeoutError (server-side statement_timeout)
+ *   connection-class codes        -> ConnectionError (see CONNECTION_ERROR_CODES)
  *
  * The original pg error is preserved as `.cause` on the wrapped error.
  */
@@ -541,7 +585,21 @@ export function wrapPgError(err) {
             return new SerializationFailureError({
                 cause: err,
             });
+        case '57014':
+            // query_canceled: a server-side statement_timeout cancelled the query.
+            // Turbine did not set the deadline (that lives in Postgres config), so
+            // there is no client-side budget to report → timeoutMs = 0.
+            return new TimeoutError(0, 'Query', {
+                message: '[turbine] Query canceled by server-side statement_timeout',
+                cause: err,
+            });
         default:
+            if (CONNECTION_ERROR_CODES.has(e.code)) {
+                const pgMessage = typeof e.message === 'string' && e.message.length > 0 ? e.message : undefined;
+                return new ConnectionError(pgMessage
+                    ? `[turbine] Database connection error: ${pgMessage}`
+                    : `[turbine] Database connection error (${e.code})`, { cause: err });
+            }
             return err;
     }
 }

package/dist/generate.js

@@ -670,7 +670,8 @@ export function generateIndex(schema, options) {
     lines.push('/**');
     lines.push(' * Create a new Turbine client instance.');
     lines.push(' *');
-    lines.push(' * @param config - Connection configuration. Falls back to DATABASE_URL env var.');
+    lines.push(' * @param config - Connection configuration. Omit it (or pass no connection');
+    lines.push(' *   fields) to fall back to the `DATABASE_URL` environment variable.');
     lines.push(' * @returns A fully-typed TurbineClient with table accessors.');
     lines.push(' */');
     lines.push('export function turbine(config?: TurbineConfig): TurbineClient {');

package/dist/powql.js

@@ -582,7 +582,7 @@ export class PowqlInterface {
         const limit = args.limit ?? args.take ?? this.defaultLimit;
         if (limit === undefined && this.warnOnUnlimited && !this.warnedUnlimited) {
             this.warnedUnlimited = true;
-            console.warn(`[turbine] findMany on "${this.table}" has no limit — this scans the whole table.`);
+            console.warn(`[turbine] findMany on "${this.table}" has no limit: this scans the whole table.`);
         }
         const limitClause = limit !== undefined ? ` limit ${this.param(limit, params)}` : '';
         const offsetClause = args.offset ? ` offset ${this.param(args.offset, params)}` : '';
@@ -1180,6 +1180,17 @@ export class PowqlInterface {
                 proj.push(`${a.alias}: ${a.fn}(${a.field ? this.ref(a.field) : `.${this.meta.primaryKey[0]}`})`);
             }
             const having = this.buildHaving(args.having, params);
+            // groupBy aggregate ordering (`_count` / `_sum` / … keys) has no PowQL
+            // equivalent here: `buildOrder` treats an `orderBy` key as a field ref, so
+            // a bare `_count: 'desc'` would silently emit an invalid `._count` sort.
+            // Refuse those keys explicitly; plain by-field ordering still flows through.
+            if (args.orderBy) {
+                for (const key of Object.keys(args.orderBy)) {
+                    if (key === '_count' || key === '_sum' || key === '_avg' || key === '_min' || key === '_max') {
+                        throw new UnsupportedFeatureError('groupBy ordering by an aggregate', 'PowDB', `orderBy key "${key}"`);
+                    }
+                }
+            }
             const order = this.buildOrder(args.orderBy);
             const powql = `${this.qt}${filter} group ${groupKeys.join(', ')}${having}${order} { ${proj.join(', ')} }`;
             const { rows } = await this.exec(powql, params, args.timeout);

package/dist/query/builder.d.ts

@@ -22,6 +22,15 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     private readonly tableMeta;
     /** SQL template cache: cacheKey → SqlCacheEntry (sql + prepared statement name) */
     private readonly sqlTemplateCache;
+    /**
+     * Whether the most recent {@link acquireSql} call was a cache HIT. Read by
+     * {@link crossCheckCache} to decide whether to run the dev-mode lockstep
+     * cross-check. Safe as a single mutable flag: each `build*()` method calls
+     * `acquireSql` then `crossCheckCache` synchronously with no intervening
+     * `await` and no re-entrant `acquireSql` (relation subqueries are built
+     * inline, not through the top-level cache).
+     */
+    private lastCacheHit;
     private readonly middlewares;
     private readonly defaultLimit?;
     private readonly warnOnUnlimited;
@@ -183,8 +192,42 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
      * On hit, increments counters and returns the cached entry.
      *
      * When `sqlCache` is disabled, always calls `build()` without caching.
+     *
+     * `build` receives a fresh `$N` param scratch array. On a miss those params
+     * are discarded (the returned params come from each call site's dedicated
+     * collect path); the array exists so the build path can number placeholders
+     * via `params.length` exactly as it does today. On a HIT, `build` is skipped
+     * here but re-run by {@link crossCheckCache} (dev only) with a fresh array to
+     * verify the collect path stayed in lockstep with the build path.
+     *
+     * Sets {@link lastCacheHit} so the caller's `crossCheckCache` knows whether a
+     * cross-check is warranted.
      */
     private acquireSql;
+    /**
+     * Dev-mode SQL-cache lockstep cross-check (see {@link cacheCrossCheckEnabled}).
+     *
+     * Runs only when the most recent {@link acquireSql} was a cache HIT and the
+     * check is enabled. Rebuilds the SQL + `$N` params fresh via the same `build`
+     * closure the caller passed to `acquireSql`, then compares:
+     *   (a) the cached SQL string byte-for-byte against the fresh SQL, and
+     *   (b) the params the cache-hit collect path produced against the fresh
+     *       build-path params (length and element-wise strict deep-equal).
+     *
+     * A mismatch means the fingerprint / build / collect paths have drifted out
+     * of lockstep (the exact class of bug that has silently corrupted results
+     * before), so it throws a {@link ValidationError} (E003) naming the
+     * fingerprint, the operation, and both SQL strings (truncated). Failing loud
+     * in dev/test is the point. Production never reaches the comparison.
+     *
+     * @param op human label of the calling build method (for the error message).
+     * @param cacheKey the cache fingerprint that HIT.
+     * @param entry the cached SQL entry that will be executed.
+     * @param build the same closure passed to `acquireSql`; re-run here to
+     *   capture the fresh build-path SQL + params.
+     * @param collectedParams the params the caller's collect path produced.
+     */
+    private crossCheckCache;
     /**
      * Reset the per-instance unlimited-query warning dedupe set.
      * Exposed for tests so a single test process can verify the warning fires
@@ -339,6 +382,20 @@ export declare class QueryInterface<T extends object, R extends object = {}> {
     buildCount(args?: CountArgs<T>): DeferredQuery<number>;
     groupBy(args: GroupByArgs<T>): Promise<Record<string, unknown>[]>;
     buildGroupBy(args: GroupByArgs<T>): DeferredQuery<Record<string, unknown>[]>;
+    /**
+     * Compile a groupBy `orderBy` into an ORDER BY body. Unlike findMany ORDER BY
+     * ({@link buildOrderBy}, which validates keys against the table's physical
+     * columns), groupBy ordering targets the columns the RESULT actually
+     * contains: plain by-fields, JSON group-key aliases, and requested aggregates
+     * (`_count` / `_sum` / `_avg` / `_min` / `_max`). Each key re-emits the exact
+     * SELECT expression that produced it (`byOrderExprs` / `aggOrderExprs`),
+     * mirroring how HAVING re-emits aggregate expressions, so no dialect ever has
+     * to accept a SELECT-alias reference in ORDER BY, and any already-bound
+     * JSON-path placeholder is reused verbatim (ORDER BY is the last clause, so
+     * no `$n` renumbering). An aggregate key that was not requested, or an unknown
+     * by-key, throws {@link ValidationError} E003 listing the valid keys.
+     */
+    private buildGroupByOrderBy;
     /**
      * Validate a JSON-path target (group key or aggregate target) in groupBy:
      * the field must resolve to a real json/jsonb column and the path must be a