KnexBridge

Generate Types. Validate Everything.

KnexBridge bridges relational databases and TypeScript applications by introspecting your schema, generating fully typed models, and producing runtime validation assets. It is designed for teams that rely on Knex.js for migrations and queries but want stronger guarantees across API layers, services, and front-end clients.

Introduction

KnexBridge automates the path from database schema to application code. By combining schema introspection, naming strategies, and template-driven code generation, it delivers TypeScript interfaces, insert/update helpers, and Zod validators that stay accurate with every migration. Engineers, data teams, and API builders who work with Knex.js can integrate it into CI pipelines or run it on demand from the CLI.

Features

• Database introspection for SQLite today, with PostgreSQL, MySQL, and SQL Server on the roadmap.
• TypeScript interface generation with configurable naming strategies and relation helpers.
• Automatic Zod schema creation for request validation and shared contracts.
• Insert and update helper types that respect excluded columns and defaults.
• Customizable type mappings and surfacing of warnings for unmapped columns.
• CLI workflow with progress reporting, metrics, and optional configuration files.

Installation

npm install --save-dev knexbridge
npm install knexbridge-core

Quick Start

Create a knexfile.js describing your Knex environments:

/** @type {import('knex').Knex.Config} */
module.exports = {
development: {
client: 'sqlite3',
connection: {
filename: './dev.sqlite',
},
useNullAsDefault: true,
},
};

Generate code into a target folder:

npx knexbridge generate --config ./knexfile.js --env development --out ./generated

Import the generated modules from your application:

import { bridge } from './generated';

Example Output

// generated/bridge.schema.ts
export interface User {
id: number;
username: string;
email?: string | null;
createdAt: Date;
}

export type UserInsert = Pick<User, 'username' | 'email'>;
export type UserUpdate = Partial<Pick<User, 'username' | 'email'>>;

// generated/bridge.validation.ts
import { z } from 'zod';

export const UserSchema = z.object({
id: z.number(),
username: z.string().min(1),
email: z.string().email().nullable(),
createdAt: z.date(),
});

Development

npm install
npm run build
npm run test

• npm run build compiles the core and CLI packages.
• npm run test performs type-level smoke tests across the workspace.

Roadmap

• Add PostgreSQL, MySQL, and SQL Server dialect support with driver autodetection.
• Generate relation-aware helper functions and query builders.
• Provide plugin hooks for custom template outputs (tRPC, OpenAPI, etc.).
• Publish official VS Code snippets and typed SDK examples.

Contributing

Code of Conduct

All contributors are expected to follow the Contributor Covenant Code of Conduct. Be respectful, constructive, and professional at all times.

Getting Started

Fork and Clone

git clone https://github.com/<your-username>/KnexBridge.git
cd KnexBridge
npm install

Build the Packages

npm run build

Run the CLI Locally

node packages/cli/dist/cli.js generate --config ./knexfile.js --out ./generated

Test

Run all tests before submitting changes:

npm test

Branching & Commits

Create a new branch for each change:

git checkout -b feature/add-postgres-support

Use conventional commits (feat:, fix:, chore:, docs:).

Keep commits atomic and messages clear.

Pull Requests

Ensure your code builds with no TypeScript errors.

Run linting before pushing:

npm run lint

Include tests for new features.

Update documentation (README, comments, etc.) when behavior changes.

Open a PR against the main branch and describe why the change matters.

Issue Guidelines

• Bug reports: include reproduction steps, environment details, and relevant logs.
• Feature requests: explain the use case and proposed API or CLI syntax.
• Discussions: use the GitHub Discussions tab for design ideas or roadmap suggestions.

Development Notes

• Node.js >= 18.18.0 is required.
• Linting configuration lives in .eslintrc.json.
• Core logic is under packages/core/src/.
• CLI code lives in packages/cli/src/.

License

Licensed under the MIT License.