kiss-orm

library2.0.3jsnpmunverified

Kiss-ORM is a minimal, opinionated ORM for TypeScript that enforces explicit SQL usage without a query builder. It uses tagged template literals (sql tag) to safely parameterize queries, preventing SQL injection. Compatible with PostgreSQL (via pg), MySQL (experimental), and SQLite (experimental). Current stable version is 2.0.3. Follows the data-mapper pattern with immutable models and no magic — no implicit database operations. Fully tested with TypeScript types included. Suitable for developers who want full SQL expressiveness with security and simplicity.

database

npm install kiss-orm

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KISS-ORM

kiss-orm

databasejavascriptv2.0.3

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.

sql

✓ import { sql } from 'kiss-orm'

✗ const sql = require('kiss-orm').sql

ESM module; sql is named export. In CommonJS use require('kiss-orm').sql

PgSqlDatabase

✓ import { PgSqlDatabase } from 'kiss-orm'

✗ import { PostgresDatabase } from 'kiss-orm'

PostgreSQL database class; named export. Also available: MySqlDatabase, SqliteDatabase

CrudRepository

✓ import { CrudRepository } from 'kiss-orm'

✗ import { Repository } from 'kiss-orm'

Base class for CRUD repositories; named export. Extend this class to create custom repositories.

MysqlDatabase

✓ import { MySqlDatabase } from 'kiss-orm'

MySQL database class; named export. Experimental – use with caution.

Sets up a PostgreSQL connection, defines a User model, and creates a repository to fetch a user by primary key.

import { sql, PgSqlDatabase, CrudRepository } from 'kiss-orm'; class UserModel { public readonly id!: number; public readonly email!: string; public readonly isBlocked!: boolean; } class UserRepository extends CrudRepository<UserModel> { constructor(database: PgSqlDatabase) { super({ database, table: 'Users', primaryKey: 'id', model: UserModel }); } } const db = new PgSqlDatabase({ host: 'localhost', port: 5432, database: 'mydb', user: 'user', password: process.env.DB_PASSWORD ?? '', }); async function main() { const repo = new UserRepository(db); const user = await repo.get(1); console.log(user.email); } main().catch(console.error);

Debug

Known issues

gotchaTemplate literal `sql` tag must be imported and used; raw strings are rejected by query methods for security.

fix

Always wrap SQL strings with the `sql` tagged template literal. Example: `db.query(sql\`SELECT * FROM users WHERE id = ${id}\`)`

affects: >=0.0.0

gotchaNullable fields in models must be typed as `string|null`, not `string|undefined`, as the database returns `null` for missing values.

fix

Use `null` union types for nullable columns in your model class properties.

affects: >=0.0.0

deprecatedMySqlDatabase and SqliteDatabase are experimental and may have breaking changes in future versions.

fix

Prefer PgSqlDatabase for production use. For MySQL or SQLite, be prepared for API changes.

affects: >=2.0.0

breakingIn v2, the `database` property in CrudRepository config changed from `connection` to `database` to align with other ORM classes.

fix

When upgrading from v1, rename `connection: db` to `database: db` in the super() call.

affects: >=2.0.0

gotchaThe `@Signale` logger is not included; you must provide your own logger or implement a mock 'info' method.

fix

Pass an object with an `info` method (and optionally `warn`, `error`) to the database constructor: `new PgSqlDatabase({...}, { info: console.log })`

affects: >=0.0.0

gotchaAll methods on Repositories return plain objects, not class instances — even though the model class is defined.

fix

Expect methods like `get`, `search` to return objects that match the model's shape but are not instances of the model class.

affects: >=0.0.0

Errors

Common errors & fixes

Cannot find module 'kiss-orm'

Package not installed or import path incorrect

fix

Install the package: `npm install kiss-orm` and ensure imports use the package name, not a relative path.

TypeError: db.query is not a function

Database instance not initialized properly or imported wrong class

fix

Ensure you instantiate the database class (e.g., `new PgSqlDatabase({...})`) and not just the config object.

Property 'id' is missing in type '{ ... }' but required in type 'UserModel'

Model properties are read-only and must match the database schema exactly

fix

Add all columns (including primary key) with `readonly` modifier and proper types (including `| null` for nullable columns).

Must use `sql` tag for queries.

Passing a raw string to a query method without the sql template literal tag

fix

Wrap the query string with the imported `sql` tag: `db.query(sql\`SELECT * FROM users WHERE id = ${id}\`)`

Upgrade

Version history

2.0.3latest on npm

Audit

Dependencies

mysqloptionalMySQL driver (optional, experimental support)

pgrequiredPostgreSQL driver

pg-formatrequiredPostgreSQL query formatting

pg-poolrequiredPostgreSQL connection pooling

sqlite3optionalSQLite driver (optional, experimental support)

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/Seb-C/kiss-orm ↗

packagekiss-orm ↗

homepagehttps://github.com/Seb-C/kiss-orm ↗