tiposaurus-rex

library1.0.0jsnpmunverified

CLI tool that generates TypeScript types from annotated MySQL SQL files. v1.0.0. Designed for teams wanting raw SQL with type safety without an ORM. Generates typed interfaces for query results and parameters, SQL constants, and optional execution helpers. MySQL-focused, uses Handlebars templates, supports watch mode. Compared to alternatives like pgtyped or sql-ts, provides explicit annotation-based configuration and built-in mysql2 integration.

database devops

npm install tiposaurus-rex

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TIPOSAURUS-REX

tiposaurus-rex

databasejavascriptv1.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

FindUserByIdResult

✓ import { FindUserByIdResult } from './generated/find-user'

✗ const FindUserByIdResult = require('./generated/find-user')

Generated interfaces are TypeScript types and cannot be used with require. Output files contain types and values.

findUserByIdQuery

✓ import { findUserByIdQuery } from './generated/find-user'

✗ import { FindUserByIdQuery } from './generated/find-user'

Query constants are generated as camelCase derived from the SQL annotation @name. Interface names start with uppercase.

mysql

✓ import mysql from 'mysql2/promise'

✗ const mysql = require('mysql2')

For runtime execution of generated queries, use the promise-based mysql2/promise with namedPlaceholders:true. CommonJS require works but lacks promise support.

Setup, generate types from annotated SQL, and execute a typed query using mysql2/promise with named placeholders.

// 1. Install npm install -D tiposaurus-rex // 2. Create src/queries/find-user.sql with: /* @name FindUserById @description Fetch a single user @param userId: number @returnType FindUserByIdResult @returnSingle true */ SELECT id, email, first_name AS firstName, is_active AS isActive FROM users WHERE id = :userId; // 3. Generate npx tiposaurus generate // 4. Use in code import mysql from 'mysql2/promise'; import { findUserByIdQuery, FindUserByIdResult } from './generated/find-user'; async function getUser(id: number) { const pool = mysql.createPool({ host: 'localhost', user: 'root', password: process.env.DB_PASSWORD ?? '', database: 'app_db', namedPlaceholders: true, }); const [rows] = await pool.execute(findUserByIdQuery, { userId: id }); const users = rows as FindUserByIdResult[]; return users[0]; }

Debug

Known issues

gotchaConfig file tiposaurus.config.json may contain database credentials. Do not commit to version control.

fix

Add tiposaurus.config.json to .gitignore, use environment variables or CI secrets.

affects: >=1.0.0

gotchaGenerated helper functions expect mysql2 connection with namedPlaceholders: true. Using other database drivers or different placeholder style will fail.

fix

Ensure mysql2 connection options include { namedPlaceholders: true } or use raw SQL constants without helpers.

affects: >=1.0.0

gotchaAnnotations (@name, @param) must follow exact syntax. Missing @name will not generate function exports.

fix

Ensure SQL files have properly formatted annotations with @name and @param keywords.

affects: >=1.0.0

gotchaOnly MySQL is supported. Using PostgreSQL or SQLite will produce incorrect type inference (e.g., boolean vs integer).

fix

Use only with MySQL databases. For other databases, consider alternatives like pgtyped.

affects: >=1.0.0

deprecatedWatch mode may have file watching issues on certain filesystems (e.g., Windows Subsystem for Linux).

fix

Restart watch mode manually if changes are not detected, or check file system permissions.

affects: >=1.0.0

Errors

Common errors & fixes

npx: command not found: tiposaurus

Package not installed or not in PATH.

fix

Run 'npm install -D tiposaurus-rex' first, then use 'npx tiposaurus generate'.

Error: Connection refused to database

MySQL database not running or config has wrong host/port/credentials.

fix

Check tiposaurus.config.json db settings, start MySQL server, verify credentials.

Cannot find module './generated/find-user'

Generated output directory not created or import path mismatch.

fix

Run 'npx tiposaurus generate' to produce files, and verify outputDir in config matches the import path.

TypeError: pool.execute is not a function

Using mysql2 callback-based client instead of promise-based.

fix

Import from 'mysql2/promise' instead of 'mysql2'.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

mysql2optionalRequired at runtime for generated helper functions which use mysql2's execute method with named placeholders

Agent activity

17 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/e2cabral/tiposaurus-rex ↗

packagetiposaurus-rex ↗

homepagehttps://github.com/e2cabral/tiposaurus-rex#readme ↗