turbine-orm 0.18.0 → 0.19.1

package/dist/cjs/query/builder.js

@@ -66,6 +66,20 @@ function isWhereOperator(value) {
     const keys = Object.keys(value);
     return keys.length > 0 && keys.every((k) => utils_js_1.OPERATOR_KEYS.has(k));
 }
+/**
+ * True for a *plain object literal* that reached an equality fallthrough
+ * without matching any known filter shape — the misspelled-operator case.
+ * Class instances (Buffer for bytea, Decimal wrappers, ...) are legitimate
+ * bind values and return false, as do arrays and Dates.
+ */
+function isUnmatchedPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value) || value instanceof Date)
+        return false;
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
 /** Known atomic-update operator keys — used to detect operator objects vs plain JSON values */
 const UPDATE_OPERATOR_KEYS = new Set(['set', 'increment', 'decrement', 'multiply', 'divide']);
 /** Known JSONB operator keys */
@@ -1723,12 +1737,24 @@ class QueryInterface {
      */
     resolveColumns(select, omit) {
         if (select) {
+            // An array here means a caller wrote `select: ['id', 'name']` (Drizzle/SQL
+            // style) instead of the object shape. Object.entries() would iterate the
+            // numeric indices and throw a cryptic `Unknown field "0"` — catch it early
+            // with an actionable message.
+            if (Array.isArray(select)) {
+                throw new errors_js_1.ValidationError(`[turbine] "select" must be an object mapping field names to true ` +
+                    `(e.g. { id: true, name: true }), not an array.`);
+            }
             // Only include columns where value is true
             return Object.entries(select)
                 .filter(([, v]) => v)
                 .map(([k]) => this.toColumn(k));
         }
         if (omit) {
+            if (Array.isArray(omit)) {
+                throw new errors_js_1.ValidationError(`[turbine] "omit" must be an object mapping field names to true ` +
+                    `(e.g. { createdAt: true }), not an array.`);
+            }
             // Include all columns except those where value is true
             const omitCols = new Set(Object.entries(omit)
                 .filter(([, v]) => v)
@@ -1932,6 +1958,16 @@ class QueryInterface {
                 parts.push(`${key}:fts(${cfg})`);
                 continue;
             }
+            // Plain object literal that matched no filter shape — give it a
+            // fingerprint distinct from real equality. The build path throws for
+            // these on non-JSON columns; sharing `key:eq` would let a cache entry
+            // warmed by genuine equality serve the bad filter silently.
+            if (isUnmatchedPlainObject(value)) {
+                parts.push(`${key}:obj(${Object.keys(value)
+                    .sort()
+                    .join(',')})`);
+                continue;
+            }
             // Plain equality
             parts.push(`${key}:eq`);
         }
@@ -1971,6 +2007,11 @@ class QueryInterface {
                 const modeStr = mode === 'insensitive' ? ':i' : '';
                 parts.push(`${key}:op(${opKeys.join(',')}${modeStr})`);
             }
+            else if (isUnmatchedPlainObject(value)) {
+                parts.push(`${key}:obj(${Object.keys(value)
+                    .sort()
+                    .join(',')})`);
+            }
             else {
                 parts.push(`${key}:eq`);
             }
@@ -2073,7 +2114,9 @@ class QueryInterface {
                 this.collectOperatorParams(value, params);
                 continue;
             }
-            // Plain equality
+            // Plain equality — same strict validation as the build path, so a
+            // cache hit can never silently bind a misspelled-operator object.
+            this.assertBindableEqualityValue(rawColumn, value, this.getColumnPgType(rawColumn), this.table);
             params.push(value);
         }
     }
@@ -2082,7 +2125,7 @@ class QueryInterface {
         const meta = this.schema.tables[targetTable];
         if (!meta)
             return;
-        for (const [_field, value] of Object.entries(subWhere)) {
+        for (const [field, value] of Object.entries(subWhere)) {
             if (value === undefined)
                 continue;
             if (value === null)
@@ -2091,6 +2134,8 @@ class QueryInterface {
                 this.collectOperatorParams(value, params);
                 continue;
             }
+            const col = meta.columnMap[field] ?? (0, schema_js_1.camelToSnake)(field);
+            this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(meta, col), targetTable);
             params.push(value);
         }
     }
@@ -2218,13 +2263,11 @@ class QueryInterface {
                     .sort();
                 subParts.push(`om=${omKeys.join(',')}`);
             }
-            // where shape (value-invariant)
+            // where shape (value-invariant, operator-shape-aware: `{title: 'x'}` and
+            // `{title: {contains: 'x'}}` emit different SQL so they must not share
+            // a fingerprint)
             if (opts.where) {
-                // Use a target-table QI if possible, or a simplified fingerprint
-                const wKeys = Object.keys(opts.where)
-                    .filter((k) => opts.where[k] !== undefined)
-                    .sort();
-                subParts.push(`w=${wKeys.join(',')}`);
+                subParts.push(`w=${this.fingerprintAliasWhere(opts.where)}`);
             }
             // orderBy shape
             if (opts.orderBy) {
@@ -2274,11 +2317,9 @@ class QueryInterface {
         //   where params → limit param → nested-with params (always, both paths).
         if (relDef.type === 'manyToMany') {
             if (spec.where) {
-                for (const [, v] of Object.entries(spec.where)) {
-                    params.push(v);
-                }
+                this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
             }
-            if (spec.limit) {
+            if (spec.limit !== undefined) {
                 params.push(Number(spec.limit));
             }
             if (spec.with) {
@@ -2291,7 +2332,9 @@ class QueryInterface {
             }
             return;
         }
-        const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || spec.orderBy !== undefined);
+        // Mirrors buildRelationSubquery's willWrap: `orderBy: {}` is treated as absent.
+        const hasOrder = spec.orderBy ? Object.values(spec.orderBy).some((dir) => dir !== undefined) : false;
+        const willWrap = relDef.type === 'hasMany' && (spec.limit !== undefined || hasOrder);
         // Non-wrapped path: nested relations BEFORE where/limit
         if (!willWrap && spec.with) {
             for (const [nestedRelName, nestedSpec] of Object.entries(spec.with)) {
@@ -2301,14 +2344,15 @@ class QueryInterface {
                 this.collectRelationSubqueryParams(nestedRelDef, nestedSpec, params, 'alias', depth + 1);
             }
         }
-        // where params
+        // where params — mirrors buildAliasWhere push order
         if (spec.where) {
-            for (const [, v] of Object.entries(spec.where)) {
-                params.push(v);
-            }
+            this.collectAliasWhereParams(targetTable, targetMeta, spec.where, params);
         }
-        // limit param
-        if (spec.limit) {
+        // limit param — only hasMany parameterizes its limit (mirrors
+        // buildRelationSubquery). belongsTo/hasOne ignore limit (always LIMIT 1), so
+        // pushing one here would orphan a param and desync the collect path.
+        // `limit: 0` pushes (LIMIT 0 is honored), so check !== undefined.
+        if (relDef.type === 'hasMany' && spec.limit !== undefined) {
             params.push(Number(spec.limit));
         }
         // Wrapped path: nested relations AFTER where/limit (inside inner subquery)
@@ -2516,6 +2560,11 @@ class QueryInterface {
                 andClauses.push(...opClauses);
                 continue;
             }
+            // Strict validation: a plain object literal that matched no known filter
+            // shape is almost always a misspelled operator (`startWith` for
+            // `startsWith`). The guard also runs on the cache-hit param-collect path
+            // (collectWhereParams) so a warmed SQL cache can never skip it.
+            this.assertBindableEqualityValue(rawColumn, value, this.getColumnPgType(rawColumn), this.table);
             // Plain equality
             params.push(value);
             andClauses.push(`${column} = ${this.p(params.length)}`);
@@ -2615,11 +2664,168 @@ class QueryInterface {
                 conditions.push(...opClauses);
                 continue;
             }
+            this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(meta, col), targetTable);
             params.push(value);
             conditions.push(`${qCol} = ${this.p(params.length)}`);
         }
         return conditions.length > 0 ? conditions.join(' AND ') : null;
     }
+    /**
+     * Resolve a column's Postgres type from an arbitrary table's metadata
+     * (relation targets, not just `this.table`).
+     */
+    pgTypeForColumn(meta, column) {
+        return meta.dialectTypes?.[column] ?? meta.pgTypes?.[column] ?? 'text';
+    }
+    /**
+     * Equality-fallthrough guard shared by every SQL-build path AND every
+     * cache-hit param-collect path. A plain object literal that matched no known
+     * filter shape on a non-JSON column is almost always a misspelled operator
+     * (`startWith` for `startsWith`); binding it as `col = $1` silently returns
+     * wrong rows. Class instances (Buffer for bytea, Decimal wrappers, ...) are
+     * legitimate bind values and pass through, as do objects on json/jsonb
+     * columns (object equality).
+     */
+    assertBindableEqualityValue(rawColumn, value, columnPgType, table) {
+        if (!isUnmatchedPlainObject(value))
+            return;
+        if (columnPgType === 'json' || columnPgType === 'jsonb')
+            return;
+        const badKeys = Object.keys(value);
+        throw new errors_js_1.ValidationError(badKeys.length === 0
+            ? `[turbine] Empty filter object on "${rawColumn}" for table "${table}". ` +
+                `Provide a value or an operator like { gt: 1 }.`
+            : `[turbine] Unknown operator${badKeys.length > 1 ? 's' : ''} ` +
+                `${badKeys.map((k) => `"${k}"`).join(', ')} on "${rawColumn}" for table "${table}". ` +
+                `Supported operators: ${[...utils_js_1.OPERATOR_KEYS].join(', ')}.`);
+    }
+    /**
+     * Build the user-supplied `where` filter of a relation `with` clause against
+     * the relation's table alias. Supports the same scalar surface as the
+     * top-level WHERE builder — equality, IS NULL, operator objects (incl.
+     * `mode: 'insensitive'`), and OR/AND/NOT combinators. Unknown operator
+     * objects throw via {@link assertBindableEqualityValue}.
+     *
+     * Param push order MUST mirror {@link collectAliasWhereParams} exactly, or
+     * cache hits and pipeline batching will desync.
+     */
+    buildAliasWhere(targetTable, targetMeta, alias, where, params) {
+        const clauses = [];
+        for (const [key, value] of Object.entries(where)) {
+            if (value === undefined)
+                continue;
+            if (key === 'OR' || key === 'AND') {
+                const arr = value;
+                if (!Array.isArray(arr) || arr.length === 0)
+                    continue;
+                const subs = arr
+                    .map((cond) => this.buildAliasWhere(targetTable, targetMeta, alias, cond, params))
+                    .filter((s) => s !== null)
+                    .map((s) => `(${s})`);
+                if (subs.length > 0)
+                    clauses.push(`(${subs.join(key === 'OR' ? ' OR ' : ' AND ')})`);
+                continue;
+            }
+            if (key === 'NOT') {
+                const sub = this.buildAliasWhere(targetTable, targetMeta, alias, value, params);
+                if (sub)
+                    clauses.push(`NOT (${sub})`);
+                continue;
+            }
+            const col = targetMeta.columnMap[key] ?? (0, schema_js_1.camelToSnake)(key);
+            if (!targetMeta.allColumns.includes(col)) {
+                throw new errors_js_1.ValidationError(`[turbine] Unknown column "${key}" in where for table "${targetTable}"`);
+            }
+            const qCol = `${alias}.${this.q(col)}`;
+            if (value === null) {
+                clauses.push(`${qCol} IS NULL`);
+                continue;
+            }
+            if (isWhereOperator(value)) {
+                clauses.push(...this.buildOperatorClauses(qCol, value, params));
+                continue;
+            }
+            this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(targetMeta, col), targetTable);
+            params.push(value);
+            clauses.push(`${qCol} = ${this.p(params.length)}`);
+        }
+        return clauses.length > 0 ? clauses.join(' AND ') : null;
+    }
+    /** Mirrors {@link buildAliasWhere} param-push order for the cache-hit collect path. */
+    collectAliasWhereParams(targetTable, targetMeta, where, params) {
+        for (const [key, value] of Object.entries(where)) {
+            if (value === undefined)
+                continue;
+            if (key === 'OR' || key === 'AND') {
+                const arr = value;
+                if (!Array.isArray(arr) || arr.length === 0)
+                    continue;
+                for (const cond of arr) {
+                    this.collectAliasWhereParams(targetTable, targetMeta, cond, params);
+                }
+                continue;
+            }
+            if (key === 'NOT') {
+                this.collectAliasWhereParams(targetTable, targetMeta, value, params);
+                continue;
+            }
+            if (value === null)
+                continue;
+            if (isWhereOperator(value)) {
+                this.collectOperatorParams(value, params);
+                continue;
+            }
+            const col = targetMeta.columnMap[key] ?? (0, schema_js_1.camelToSnake)(key);
+            this.assertBindableEqualityValue(col, value, this.pgTypeForColumn(targetMeta, col), targetTable);
+            params.push(value);
+        }
+    }
+    /**
+     * Value-invariant, shape-aware fingerprint for a relation `with` clause's
+     * `where` filter. Must distinguish every SQL shape {@link buildAliasWhere}
+     * can emit — equality vs null vs operator sets vs combinators — or two
+     * differently-shaped wheres would share one cached SQL string.
+     */
+    fingerprintAliasWhere(where) {
+        const keys = Object.keys(where)
+            .filter((k) => where[k] !== undefined)
+            .sort();
+        const parts = [];
+        for (const key of keys) {
+            const value = where[key];
+            if (key === 'OR' || key === 'AND') {
+                const arr = value;
+                if (!Array.isArray(arr) || arr.length === 0)
+                    continue;
+                parts.push(`${key}[${arr.map((c) => this.fingerprintAliasWhere(c)).join(',')}]`);
+                continue;
+            }
+            if (key === 'NOT') {
+                parts.push(`NOT(${this.fingerprintAliasWhere(value)})`);
+                continue;
+            }
+            if (value === null) {
+                parts.push(`${key}:null`);
+                continue;
+            }
+            if (isWhereOperator(value)) {
+                const opKeys = Object.keys(value)
+                    .filter((k) => k !== 'mode')
+                    .sort();
+                const mode = value.mode;
+                parts.push(`${key}:op(${opKeys.join(',')}${mode === 'insensitive' ? ':i' : ''})`);
+                continue;
+            }
+            if (isUnmatchedPlainObject(value)) {
+                parts.push(`${key}:obj(${Object.keys(value)
+                    .sort()
+                    .join(',')})`);
+                continue;
+            }
+            parts.push(`${key}:eq`);
+        }
+        return parts.join('&');
+    }
     /**
      * Build SQL clauses for a single operator object on a column.
      * Each operator key becomes its own clause, all ANDed together.
@@ -2699,7 +2905,8 @@ class QueryInterface {
         return Object.entries(orderBy)
             .map(([key, dir]) => {
             if (meta && !(key in meta.columnMap)) {
-                throw new errors_js_1.ValidationError(`Unknown column "${key}" in orderBy for table "${this.table}"`);
+                throw new errors_js_1.ValidationError(`[turbine] Unknown field "${key}" in orderBy on table "${this.table}". ` +
+                    `Known fields: ${Object.keys(meta.columnMap).join(', ') || '(none)'}.`);
             }
             // Vector KNN ordering: { distance: { to, metric, direction? } }
             if (isVectorOrderBy(dir)) {
@@ -3065,7 +3272,11 @@ class QueryInterface {
         // Determine if this hasMany will take the wrapped subquery path (LIMIT or ORDER BY).
         // When wrapping, nested relations are built in the wrapped path referencing innerAlias,
         // so we must NOT build them here (they would push orphaned params).
-        const willWrap = relDef.type === 'hasMany' && spec !== true && (spec.limit !== undefined || spec.orderBy !== undefined);
+        // An orderBy with no defined entries (`orderBy: {}`) is treated as absent —
+        // it must neither trigger the wrap (dropping nested relations) nor render a
+        // dangling `ORDER BY `. `limit: 0` is meaningful (LIMIT 0) and DOES wrap.
+        const relOrderEntries = spec !== true && spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
+        const willWrap = relDef.type === 'hasMany' && spec !== true && (spec.limit !== undefined || relOrderEntries.length > 0);
         // manyToMany takes a dedicated JOIN-through-junction path. Nested relations,
         // where, orderBy, and select/omit are handled there (the target alias is the
         // row source, exactly like hasMany), so short-circuit before the hasMany logic.
@@ -3093,14 +3304,14 @@ class QueryInterface {
         const qTarget = this.q(targetTable);
         // Build ORDER BY for json_agg
         let orderClause = '';
-        if (spec !== true && spec.orderBy) {
-            const orders = Object.entries(spec.orderBy)
+        if (relOrderEntries.length > 0) {
+            const orders = relOrderEntries
                 .map(([k, dir]) => {
                 const col = (0, schema_js_1.camelToSnake)(k);
                 if (!targetMeta.allColumns.includes(col)) {
                     throw new errors_js_1.ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
                 }
-                const safeDir = dir.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+                const safeDir = String(dir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
                 return `${alias}.${this.q(col)} ${safeDir}`;
             })
                 .join(', ');
@@ -3117,20 +3328,21 @@ class QueryInterface {
         else {
             whereClause = this.dialect.buildCorrelation(alias, relDef.foreignKey, qParent, relDef.referenceKey);
         }
-        // Additional filters — properly parameterized
+        // Additional filters — full scalar where surface (equality, null, operator
+        // objects, OR/AND/NOT), properly parameterized against this alias.
         if (spec !== true && spec.where) {
-            for (const [k, v] of Object.entries(spec.where)) {
-                const col = (0, schema_js_1.camelToSnake)(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new errors_js_1.ValidationError(`[turbine] Unknown column "${k}" in where for table "${targetTable}"`);
-                }
-                params.push(v);
-                whereClause += ` AND ${alias}.${this.q(col)} = ${this.p(params.length)}`;
-            }
-        }
-        // LIMIT
+            const extra = this.buildAliasWhere(targetTable, targetMeta, alias, spec.where, params);
+            if (extra)
+                whereClause += ` AND ${extra}`;
+        }
+        // LIMIT — only meaningful for hasMany. A belongsTo / hasOne subquery returns
+        // a single row (literal `LIMIT 1` below), so a `spec.limit` here must NOT push
+        // a parameter: doing so orphans an untyped `$N` that the SQL never references,
+        // which Postgres rejects with "could not determine data type of parameter $N"
+        // (and shifts every later placeholder by one). To-one relations ignore limit.
+        // `limit: 0` is honored (LIMIT 0 → empty array), so check !== undefined.
         let limitClause = '';
-        if (spec !== true && spec.limit) {
+        if (relDef.type === 'hasMany' && spec !== true && spec.limit !== undefined) {
             params.push(Number(spec.limit));
             limitClause = ` LIMIT ${this.p(params.length)}`;
         }
@@ -3224,35 +3436,33 @@ class QueryInterface {
         let whereClause = sourceKeys
             .map((jcol, i) => `${jalias}.${this.q(jcol)} = ${qParent}.${this.q(refKeys[i])}`)
             .join(' AND ');
-        // ORDER BY on the target rows
+        // ORDER BY on the target rows. `orderBy: {}` (no defined entries) is
+        // treated as absent — it must not render a dangling `ORDER BY `.
+        const relOrderEntries = spec !== true && spec.orderBy ? Object.entries(spec.orderBy).filter(([, dir]) => dir !== undefined) : [];
         let orderClause = '';
-        if (spec !== true && spec.orderBy) {
-            const orders = Object.entries(spec.orderBy)
+        if (relOrderEntries.length > 0) {
+            const orders = relOrderEntries
                 .map(([k, dir]) => {
                 const col = (0, schema_js_1.camelToSnake)(k);
                 if (!targetMeta.allColumns.includes(col)) {
                     throw new errors_js_1.ValidationError(`[turbine] Unknown column "${k}" in orderBy for table "${targetTable}"`);
                 }
-                const safeDir = dir.toLowerCase() === 'desc' ? 'DESC' : 'ASC';
+                const safeDir = String(dir).toLowerCase() === 'desc' ? 'DESC' : 'ASC';
                 return `${talias}.${this.q(col)} ${safeDir}`;
             })
                 .join(', ');
             orderClause = ` ORDER BY ${orders}`;
         }
-        // Additional WHERE filters on the target — properly parameterized.
+        // Additional WHERE filters on the target — full scalar where surface,
+        // properly parameterized against the target alias.
         if (spec !== true && spec.where) {
-            for (const [k, v] of Object.entries(spec.where)) {
-                const col = (0, schema_js_1.camelToSnake)(k);
-                if (!targetMeta.allColumns.includes(col)) {
-                    throw new errors_js_1.ValidationError(`[turbine] Unknown column "${k}" in where for table "${targetTable}"`);
-                }
-                params.push(v);
-                whereClause += ` AND ${talias}.${this.q(col)} = ${this.p(params.length)}`;
-            }
+            const extra = this.buildAliasWhere(targetTable, targetMeta, talias, spec.where, params);
+            if (extra)
+                whereClause += ` AND ${extra}`;
         }
-        // LIMIT
+        // LIMIT — `limit: 0` is honored (LIMIT 0 → empty array)
         let limitClause = '';
-        if (spec !== true && spec.limit) {
+        if (spec !== true && spec.limit !== undefined) {
             params.push(Number(spec.limit));
             limitClause = ` LIMIT ${this.p(params.length)}`;
         }

package/dist/cli/index.js

@@ -20,14 +20,14 @@
  *   npx turbine init --url postgres://...
  *   npx turbine migrate create add_users_table
  */
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { generate } from '../generate.js';
 import { introspect } from '../introspect.js';
 import { schemaDiff, schemaPush } from '../schema-sql.js';
 import { configTemplate, findConfigFile, loadConfig, resolveConfig } from './config.js';
-import { needsTsLoader, registerTsLoader } from './loader.js';
+import { canResolveTsx, getTsLoaderError, needsTsLoader, registerTsLoader } from './loader.js';
 import { createMigration, listMigrationFiles, migrateDown, migrateStatus, migrateUp } from './migrate.js';
 import { startObserve } from './observe.js';
 import { startStudio } from './studio.js';
@@ -132,6 +132,15 @@ function failMissingTsLoader(filePath, reason) {
         console.log(`  ${dim('Your Node.js version does not support')} ${cyan('module.register()')}.`);
         console.log(`  ${dim('Upgrade to Node.js')} ${cyan('20.6+')} ${dim('or use a')} ${cyan('.js')} ${dim('/')} ${cyan('.mjs')} ${dim('config file.')}`);
     }
+    else if (reason === 'failed') {
+        // tsx IS installed but registering its loader threw. Report the real
+        // cause — telling the user to install tsx here would be a misdiagnosis.
+        console.log(`  ${dim('tsx is installed, but registering its TypeScript loader failed:')}`);
+        newline();
+        console.log(`    ${getTsLoaderError() ?? '(unknown error)'}`);
+        newline();
+        console.log(`  ${dim('Try upgrading tsx:')} ${cyan('npm install --save-dev tsx@latest')}${dim(', or rename your file to')} ${cyan('.mjs')}.`);
+    }
     else {
         console.log(`  ${dim('Loading .ts config / schema files requires')} ${cyan('tsx')} ${dim('to be installed.')}`);
         newline();
@@ -175,7 +184,7 @@ async function loadSchemaFile(schemaFile) {
     // ERR_UNKNOWN_FILE_EXTENSION for `.ts`.
     if (needsTsLoader(absPath)) {
         const status = await registerTsLoader();
-        if (status === 'missing' || status === 'unsupported') {
+        if (status === 'missing' || status === 'unsupported' || status === 'failed') {
             failMissingTsLoader(schemaFile, status);
         }
     }
@@ -311,7 +320,7 @@ export default defineSchema({
   //   id: { type: 'serial', primaryKey: true },
   //   email: { type: 'text', notNull: true, unique: true },
   //   name: { type: 'text', notNull: true },
-  //   created_at: { type: 'timestamptz', default: 'NOW()' },
+  //   created_at: { type: 'timestamp', default: 'NOW()' },
   // },
 });
 `, 'utf-8');
@@ -374,6 +383,9 @@ export default defineSchema({
             console.log(`     ${dim('or create a')} ${cyan('.env')} ${dim('file with')} ${cyan('DATABASE_URL=postgres://...')}`);
         }
         console.log(`  ${dim('2.')} Run ${cyan('npx turbine generate')} to introspect your DB`);
+        if (!canResolveTsx()) {
+            console.log(`     ${dim('Note: the TypeScript config requires')} ${cyan('tsx')} ${dim('—')} ${cyan('npm install --save-dev tsx')}`);
+        }
     }
     else {
         console.log(`  ${dim('1.')} Import the generated client:`);
@@ -1214,7 +1226,17 @@ function showVersion() {
     // Using process.argv[1] instead of import.meta.url so the same code compiles
     // cleanly for both the ESM and CJS builds.
     try {
-        let dir = dirname(process.argv[1] ?? '');
+        // Resolve symlinks first: `npx turbine` runs via node_modules/.bin/turbine,
+        // a symlink whose dirname would walk the CONSUMER's tree and never find
+        // turbine-orm's package.json (printing no version number at all).
+        let entry = process.argv[1] ?? '';
+        try {
+            entry = realpathSync(entry);
+        }
+        catch {
+            // keep the raw path if realpath fails (e.g. deleted cwd)
+        }
+        let dir = dirname(entry);
         for (let i = 0; i < 6; i++) {
             const candidate = resolve(dir, 'package.json');
             if (existsSync(candidate)) {
@@ -1262,7 +1284,7 @@ async function main() {
     const configPath = findConfigFile();
     if (needsTsLoader(configPath)) {
         const status = await registerTsLoader();
-        if (status === 'missing' || status === 'unsupported') {
+        if (status === 'missing' || status === 'unsupported' || status === 'failed') {
             failMissingTsLoader(configPath ?? 'turbine.config.ts', status);
         }
     }

package/dist/cli/loader.d.ts

@@ -8,9 +8,18 @@
  *
  * Strategy:
  *   1. If the file we're about to import ends in `.ts` / `.mts` / `.cts`,
- *      probe whether `tsx/esm` is resolvable from the user's CWD.
- *   2. If yes, call `module.register('tsx/esm', ...)` ONCE per process.
- *   3. If no, surface an actionable error telling the user to install `tsx`.
+ *      probe whether `tsx` is resolvable from the user's CWD.
+ *   2. Prefer tsx's supported programmatic API, `tsx/esm/api`'s `register()`.
+ *      Calling Node's `module.register('tsx/esm', ...)` directly throws
+ *      "tsx must be loaded with --import instead of --loader" on every Node
+ *      version that has `module.register()` (>= 20.6) — tsx's hook file
+ *      guards against being loaded that way. The `tsx/esm/api` entry point
+ *      is the documented path and works everywhere `module.register()` does.
+ *   3. Fall back to `module.register('tsx/esm', ...)` only for very old tsx
+ *      versions (< 4.0) that predate `tsx/esm/api`.
+ *   4. If tsx isn't installed, or registration genuinely fails, surface an
+ *      actionable error — including the REAL underlying error message, never
+ *      a misdiagnosed "tsx is not installed".
  *
  * `tsx` is intentionally NOT a runtime dependency — many projects already
  * have it, and adding a heavy dev tool to a 1-dependency ORM would be silly.
@@ -28,7 +37,12 @@ export declare function needsTsLoader(filePath: string | null | undefined): bool
  * Accepts an injected `resolver` so unit tests don't need a real filesystem.
  */
 export declare function canResolveTsx(resolver?: (id: string) => string): boolean;
-export type TsLoaderStatus = 'registered' | 'already' | 'unsupported' | 'missing';
+export type TsLoaderStatus = 'registered' | 'already' | 'unsupported' | 'missing' | 'failed';
+/**
+ * The underlying error message from the last failed registration attempt,
+ * or null. Lets the CLI report the REAL cause instead of guessing.
+ */
+export declare function getTsLoaderError(): string | null;
 /**
  * Register the tsx ESM loader so subsequent dynamic imports of `.ts` files
  * work. Safe to call multiple times — internal flag prevents double registration.
@@ -36,8 +50,11 @@ export type TsLoaderStatus = 'registered' | 'already' | 'unsupported' | 'missing
  * Returns:
  *   - 'registered'  loader was successfully registered this call
  *   - 'already'     a loader was previously registered (idempotent)
- *   - 'unsupported' Node lacks `module.register()` (Node < 20.6)
+ *   - 'unsupported' Node lacks `module.register()` (Node < 20.6) and tsx has
+ *                   no programmatic API to fall back to
  *   - 'missing'     `tsx` is not installed in the user's project
+ *   - 'failed'      tsx IS installed but registration threw — see
+ *                   {@link getTsLoaderError} for the underlying message
  */
 export declare function registerTsLoader(): Promise<TsLoaderStatus>;
 /** Reset the loader state — used by unit tests only. */