turbine-orm 0.19.0 → 0.19.2

package/dist/cjs/query/utils.js

@@ -109,6 +109,7 @@ function sqlToPreparedName(sql) {
 }
 /** Known operator keys — used to detect operator objects vs plain values */
 exports.OPERATOR_KEYS = new Set([
+    'equals',
     'gt',
     'gte',
     'lt',

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:`);
@@ -1117,13 +1129,15 @@ function showMigrateHelp() {
     newline();
     console.log(`  ${bold('Options:')}`);
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}   Postgres connection string`);
+    console.log(`    ${cyan('--auto')}            Auto-generate UP/DOWN SQL from schema diff ${dim('(create only)')}`);
     console.log(`    ${cyan('--step, -n')} ${dim('<N>')}    Number of migrations to apply/rollback`);
-    console.log(`    ${cyan('--dry-run')}          Show SQL without executing`);
-    console.log(`    ${cyan('--allow-drift')}      Bypass checksum validation ${dim('(migrate up only — advanced)')}`);
-    console.log(`    ${cyan('--verbose, -v')}      Show detailed output`);
+    console.log(`    ${cyan('--dry-run')}         Show SQL without executing`);
+    console.log(`    ${cyan('--allow-drift')}     Bypass checksum validation ${dim('(migrate up only — advanced)')}`);
+    console.log(`    ${cyan('--verbose, -v')}     Show detailed output`);
     newline();
     console.log(`  ${bold('Examples:')}`);
     console.log(`    ${dim('$')} npx turbine migrate create add_users_table`);
+    console.log(`    ${dim('$')} npx turbine migrate create add_email_index --auto`);
     console.log(`    ${dim('$')} npx turbine migrate up`);
     console.log(`    ${dim('$')} npx turbine migrate down --step 2`);
     console.log(`    ${dim('$')} npx turbine migrate status`);
@@ -1168,16 +1182,17 @@ function showHelp() {
     newline();
     console.log(`  ${bold('Commands:')}`);
     console.log(`    ${cyan('init')}               Initialize a Turbine project`);
-    console.log(`    ${cyan('generate')} ${dim('| pull')}   Introspect database ${symbols.arrow} generate types`);
+    console.log(`    ${cyan('generate')} ${dim('| pull')}    Introspect database ${symbols.arrow} generate types`);
     console.log(`    ${cyan('push')}               Apply schema definitions to database`);
-    console.log(`    ${cyan('migrate')} ${dim('<sub>')}     SQL migration management`);
-    console.log(`      ${dim('create <name>')}     Create a new migration file`);
+    console.log(`    ${cyan('migrate')} ${dim('<sub>')}      SQL migration management`);
+    console.log(`      ${dim('create <name>')}    Create a new migration file`);
     console.log(`      ${dim('up')}               Apply pending migrations`);
     console.log(`      ${dim('down')}             Rollback last migration`);
     console.log(`      ${dim('status')}           Show applied/pending migrations`);
     console.log(`    ${cyan('seed')}               Run seed file`);
-    console.log(`    ${cyan('status')} ${dim('| info')}     Show schema summary`);
+    console.log(`    ${cyan('status')} ${dim('| info')}      Show schema summary`);
     console.log(`    ${cyan('studio')}             Launch local read-only web UI`);
+    console.log(`    ${cyan('observe')}            Launch metrics dashboard ${dim('(requires TURBINE_OBSERVE_URL)')}`);
     newline();
     console.log(`  ${bold('Options:')}`);
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}      Postgres connection string`);
@@ -1189,8 +1204,13 @@ function showHelp() {
     console.log(`    ${cyan('--verbose, -v')}        Show detailed output`);
     console.log(`    ${cyan('--force, -f')}          Overwrite existing files`);
     newline();
-    console.log(`  ${bold('Studio options:')}`);
-    console.log(`    ${cyan('--port')} ${dim('<n>')}           HTTP port ${dim('(default: 4983)')}`);
+    console.log(`  ${bold('Migrate options:')}`);
+    console.log(`    ${cyan('--auto')}               Auto-generate UP/DOWN SQL from schema diff ${dim('(create)')}`);
+    console.log(`    ${cyan('--step, -n')} ${dim('<N>')}       Number of migrations to apply/rollback`);
+    console.log(`    ${cyan('--allow-drift')}        Bypass checksum validation on ${cyan('migrate up')} ${dim('(advanced)')}`);
+    newline();
+    console.log(`  ${bold('Studio / observe options:')}`);
+    console.log(`    ${cyan('--port')} ${dim('<n>')}           HTTP port ${dim('(default: 4983 studio, 4984 observe)')}`);
     console.log(`    ${cyan('--host')} ${dim('<addr>')}        Bind address ${dim('(default: 127.0.0.1)')}`);
     console.log(`    ${cyan('--no-open')}            Don't auto-open the browser`);
     newline();
@@ -1214,7 +1234,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 +1292,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. */

package/dist/cli/loader.js

@@ -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.
@@ -50,6 +59,14 @@ export function canResolveTsx(resolver) {
     }
 }
 let tsLoaderState = null;
+let tsLoaderError = null;
+/**
+ * The underlying error message from the last failed registration attempt,
+ * or null. Lets the CLI report the REAL cause instead of guessing.
+ */
+export function getTsLoaderError() {
+    return tsLoaderError;
+}
 /**
  * Register the tsx ESM loader so subsequent dynamic imports of `.ts` files
  * work. Safe to call multiple times — internal flag prevents double registration.
@@ -57,17 +74,51 @@ let tsLoaderState = null;
  * 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 async function registerTsLoader() {
     if (tsLoaderState === 'registered' || tsLoaderState === 'already') {
         return 'already';
     }
+    const userRequire = createRequire(`${process.cwd()}/`);
+    // Preferred: tsx's supported programmatic API (tsx >= 4.0).
+    let apiPath = null;
+    try {
+        apiPath = userRequire.resolve('tsx/esm/api');
+    }
+    catch {
+        apiPath = null;
+    }
+    if (apiPath) {
+        try {
+            const api = (await import(pathToFileURL(apiPath).href));
+            if (typeof api.register !== 'function') {
+                throw new Error(`tsx/esm/api resolved at ${apiPath} but exports no register() function`);
+            }
+            api.register();
+            tsLoaderState = 'registered';
+            tsLoaderError = null;
+            return 'registered';
+        }
+        catch (err) {
+            tsLoaderState = 'failed';
+            tsLoaderError = err instanceof Error ? err.message : String(err);
+            return 'failed';
+        }
+    }
+    // tsx/esm/api not resolvable — is tsx installed at all?
     if (!canResolveTsx()) {
         tsLoaderState = 'missing';
         return 'missing';
     }
+    // Legacy fallback for tsx < 4.0 (no tsx/esm/api): Node's module.register.
+    // On tsx >= 4.19 this path throws ("tsx must be loaded with --import
+    // instead of --loader") — but those versions all ship tsx/esm/api, so we
+    // only land here for genuinely old installs.
     try {
         const mod = await import('node:module');
         const register = mod.register;
@@ -77,15 +128,18 @@ export async function registerTsLoader() {
         }
         register('tsx/esm', pathToFileURL(`${process.cwd()}/`));
         tsLoaderState = 'registered';
+        tsLoaderError = null;
         return 'registered';
     }
-    catch {
-        tsLoaderState = 'missing';
-        return 'missing';
+    catch (err) {
+        tsLoaderState = 'failed';
+        tsLoaderError = err instanceof Error ? err.message : String(err);
+        return 'failed';
     }
 }
 /** Reset the loader state — used by unit tests only. */
 export function _resetTsLoaderStateForTests() {
     tsLoaderState = null;
+    tsLoaderError = null;
 }
 //# sourceMappingURL=loader.js.map

package/dist/cli/migrate.d.ts

@@ -113,8 +113,8 @@ export declare function deriveLockId(databaseName: string): number;
  */
 export declare function migrateUp(connectionString: string, migrationsDir: string, options?: {
     step?: number;
-    allowDrift?: boolean /** @deprecated use allowDrift */;
-    force?: boolean;
+    allowDrift?: boolean;
+    force?: boolean /** @deprecated use allowDrift */;
     adapter?: DatabaseAdapter;
     dialect?: Dialect;
 }): Promise<{