lil-orm

Lil ORM

Lil ORM is a lightweight SQLite ORM designed for Node.js. This compact project prioritizes clarity and simplicity in its API, making it effortless to interact with SQLite databases. Although it's a lightweight ORM, it boasts a robust set of capabilities, letting developers create intricate database queries with ease.

While Lil ORM is primarily intended as a learning resource and experimental project, its lean design and user-friendly approach make it a noteworthy tool for those looking to understand the nuances of building APIs without the complexity that often accompanies larger ORMs.

Please note: Lil ORM is currently not recommended for use in production environments (yet), but rather as a learning tool and sandbox for testing and development purposes

⚠️ API are subjected to change ⚠️

Install

npm i lil-orm

Define Entity

@Entity('user')
class UserEntity {
  @PrimaryKey({
    autoIncrement: true,
  })
  @Column({
    type: 'INTEGER',
    name: 'id',
  })
  id: number;

  @Column({
    type: 'TEXT',
    name: 'name',
  })
  name: string;

  @Column({
    type: 'TEXT',
    name: 'email',
  })
  email: string;

  @Column({
    type: 'JSON',
    name: 'config',
  })
  config: any;

  @Column({
    type: 'BOOLEAN',
    name: 'is_active',
  })
  isActive: boolean;

  @Column({
    type: 'DATE',
    name: 'created_at',
  })
  createdAt: Date;
}

supported types:

• TEXT

• INTEGER

• REAL

• BOOLEAN

• DATE (ISO Format)

• JSON

⚠️ Warning: Important Configuration Required

To ensure proper functioning of the library, please make sure to configure your TypeScript project correctly.

"experimentalDecorators": true,
"emitDecoratorMetadata": true,
"esModuleInterop": true,

Other configurations

Option 1: Enable useDefineForClassFields

In your project's tsconfig.json, add or modify the compilerOptions section to include the following:

{
  "compilerOptions": {
    "useDefineForClassFields": true
  }
}

Option 2: Initialize Every Property with Default Values

If you cannot enable useDefineForClassFields or prefer not to modify your TypeScript configuration, make sure to explicitly initialize every property in your entity class with a default value.

For example:

@Entity('tableName')
class MyEntity {
  @PrimaryKey({
    autoIncrement: true,
  })
  @Column({
    type: 'INTEGER'
  })
  id: number = 0;
  
  @Column({
    type: 'TEXT'
  })
  name: string = '';
  // ...other properties
}

Module Setup

import { LilORM } from 'lil-orm';

const databaseConnectionString = ':memory:';

const module = new LilORM(databaseConnectionString);

Create Table

(experimental API name)

module.createTable(UserEntity) //to create a table from an entity

CRUD Operations

//get repository
const repository = module.getRepository<UserEntity>(UserEntity);

//Insert 
const userEntity = new UserEntity();
userEntity.id = 1;
userEntity.name = 'test';
userEntity.email = '[e-mail]';
userEntity.isActive = false;
userEntity.age = 42;
userEntity.config = null;
userEntity.createdAt = new Date();

await repository.insert(userEntity);

//Find by id
const users = await repository.retrieve(qb => qb.where('id').equals(1));

//Update
userEntity.name = 'updated';
await repository.update(userEntity, qb => qb.where('id').equals(1));

//Delete
await repository.delete({ id: 69 });

Custom query with query builder

let user: any[] = lilOrm.retrieve<UserEntity>(
            qb => qb.forEntity(UserEntity)
            .where('isActive').equals(true)
            .and('age').greaterThan(18)
            .or('config').equals({ allowed: true })
            .finalize(), 
            (data) => data)

Transactions

TO-DO