Gimlet

2.1.0 verified Sat Apr 25 auth: no javascript

Gimlet is a Node.js module that provides a lightweight database access layer on top of common drivers like MySQL. It adds high-level validations, helper methods (create, remove, queryRow, queryOne), and Record instances with change tracking, saving, and freezing capabilities. As of v2.1.0, it is actively maintained with gradual updates. Unlike ORMs/ODMs, developers write raw SQL queries. Dependencies: mysql driver must be installed separately.

Common errors

error Cannot find module 'gimlet' ↓

cause Package not installed or missing from node_modules

fix

npm install gimlet

error Error: connect ECONNREFUSED ↓

cause MySQL server not running or incorrect host/port

fix

Start MySQL or verify connection string: mysql://user:pass@localhost:3306/db

Warnings

gotcha gimlet.connect() does not immediately connect for MySQL; first query triggers connection. ↓

fix Call connection.open(cb) if you need immediate connection check.

deprecated gimlet types Point/Polygon constructor may change in future; prefer plain objects if possible. ↓

fix Use driver-specific POINT handling if stability is critical.

gotcha Record.save() will fail if connection is closed or pool drained. ↓

fix Ensure connection is open before calling save, or handle errors.

Install

npm install gimlet

yarn add gimlet

pnpm add gimlet

Imports

default
wrong
```
const gimlet = require('gimlet')
```
correct
```
import gimlet from 'gimlet'
```
ESM requires Node >=16 or type: module. CJS require still works.

Gimlet

wrong

import { Gimlet } from 'gimlet'

correct

import Gimlet from 'gimlet'

Default export is the constructor/object.

types

wrong

import types from 'gimlet/types'

correct

import { types } from 'gimlet'

Named export for Point/Polygon types.

Quickstart

Connect to MySQL, query users, modify a record, and save changes.

import gimlet from 'gimlet';
import mysql from 'mysql'; // must install separately

const connection = gimlet.connect('mysql://user:pass@localhost/db');
const handler = connection.handler();

handler.query('SELECT * FROM users', (err, users) => {
  if (err) throw err;
  console.log(users[0] instanceof gimlet.Record); // true
  console.log(users[0].name);
  users[0].name = 'Updated';
  users[0].save(err => console.log('saved'));
});