simple-typed-sql

library0.8.6jsnpmunverified

TypeScript SQL query builder with type-safe column references and auto-completion. Current stable version is 0.8.6, released as a single major version since 2016. Unlike Knex.js or TypeORM, it provides partial type safety by mapping TypeScript interfaces to database tables, eliminating string-based column names. Supports SELECT, INSERT, UPDATE, JOINs, WHERE clauses (including complex conditions), transactions, and aggregation. Under the hood: Knex.js for query execution. Release cadence is low, with ongoing work on SELECT expressions. Key limitation: only partial type safety (not full compile-time checks). Ships TypeScript types.

database

npm install simple-typed-sql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SIMPLE-TYPED-SQL

simple-typed-sql

databasejavascriptv0.8.6

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.

Mapper

✓ import { Mapper } from 'simple-typed-sql';

✗ import Mapper from 'simple-typed-sql';

Named export; no default export.

defineMapping

✓ import { defineMapping } from 'simple-typed-sql';

✗ import { defineMapping } from 'simple-typed-sql/mapping';

Named export from main module.

defineNumber

✓ import { defineNumber } from 'simple-typed-sql';

✗ import { defineNumber } from 'simple-typed-sql/definitions';

Access via main module.

Shows full setup: knex client, Mapper, table mapping, table creation, insert, and select.

import knex from 'knex'; import { Mapper, defineMapping, defineNumber, defineString, defineDatetime } from 'simple-typed-sql'; const knexClient = knex({ client: 'sqlite3', connection: { filename: ':memory:' }, useNullAsDefault: true }); const mapper = new Mapper(knexClient); const fooMapping = defineMapping('foo_table', { id: defineNumber(), name: defineString(), createdTime: defineDatetime({ fieldName: 'created_time' }), fooCount: defineNumber({ fieldName: 'foo_count' }) }); (async () => { await knexClient.schema.createTable('foo_table', (table) => { table.increments('id'); table.string('name'); table.datetime('created_time'); table.integer('foo_count'); }); await mapper.insertInto(fooMapping, { id: 1, name: 'foo1', createdTime: new Date(), fooCount: 5 }); const foos = await mapper.selectAllFrom(fooMapping); console.log(foos); })().catch(console.error);

Debug

Known issues

breakingOnly partial type safety — column names are type-checked, but not all SQL constructs (e.g., subqueries) enforce type constraints at compile time.

fix

Use TypeScript strict mode and manually verify complex queries.

affects: >=0.0.0

gotchaMapper instances must be created with a Knex client; they are not standalone.

fix

Always pass a configured knex instance to the Mapper constructor.

affects: >=0.0.0

gotchaTable name in defineMapping must match actual SQL table name; no automatic pluralization or case conversion.

fix

Use exact database table names as strings.

affects: >=0.0.0

deprecatedSQLite3 requires useNullAsDefault: true in knex config, otherwise insert may fail.

fix

Add useNullAsDefault: true to knex configuration when using SQLite3.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'simple-typed-sql'

Package not installed or version mismatch.

fix

npm install simple-typed-sql@latest

TypeError: knex is not a function

Importing knex incorrectly (using default import in CJS context).

fix

Use 'import knex from "knex"' for ESM or 'const knex = require("knex");' for CJS.

Property 'fooCount' does not exist on type '...'

TypeScript can't infer type for properties with custom fieldName.

fix

Ensure fieldName in defineNumber({ fieldName: 'foo_count' }) matches DB column; type may need explicit assertion.

Upgrade

Version history

0.8.6latest on npm

Audit

Dependencies

knexrequiredUnderlying query builder and execution engine

Agent activity

11 hits · last 30 days

node