{"id":16382922,"url":"https://github.com/dresende/gimlet","last_synced_at":"2026-05-08T12:05:19.962Z","repository":{"id":20342377,"uuid":"23617012","full_name":"dresende/gimlet","owner":"dresende","description":"NodeJS module for database access built on top of commonly used database drivers","archived":false,"fork":false,"pushed_at":"2025-01-23T15:43:17.000Z","size":395,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-18T17:24:52.554Z","etag":null,"topics":["database","driver","javascript","mysql"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dresende.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-09-03T10:59:49.000Z","updated_at":"2024-06-11T14:08:51.000Z","dependencies_parsed_at":"2024-11-02T02:45:27.433Z","dependency_job_id":null,"html_url":"https://github.com/dresende/gimlet","commit_stats":{"total_commits":173,"total_committers":3,"mean_commits":"57.666666666666664","dds":0.1560693641618497,"last_synced_commit":"eb2518a2fecb565890713fcece8c6c340e35f7a9"},"previous_names":[],"tags_count":59,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dresende%2Fgimlet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dresende%2Fgimlet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dresende%2Fgimlet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dresende%2Fgimlet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dresende","download_url":"https://codeload.github.com/dresende/gimlet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245052646,"owners_count":20553162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","driver","javascript","mysql"],"created_at":"2024-10-11T04:06:51.459Z","updated_at":"2026-05-08T12:05:19.859Z","avatar_url":"https://github.com/dresende.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Gimlet\n\n[![Build Status](https://api.travis-ci.org/dresende/gimlet.svg?branch=master)](http://travis-ci.org/dresende/gimlet)\n[![Coverage Status](https://img.shields.io/coveralls/dresende/gimlet.svg)](https://coveralls.io/r/dresende/gimlet?branch=master)\n[![Published Version](https://badge.fury.io/js/gimlet.svg)](https://npmjs.org/package/gimlet)\n\nGimlet is a NodeJS module for database access built on top of commonly used database drivers. It gives some high level validations and helper methods on top of returned rows. This is not an ORM/ODM, queries must still be made by hand (more or less..).\n\n### Installation\n\nGimlet is available on NPM.\n\n```sh\nnpm install gimlet\n```\n\nSince gimlet uses other drivers you must install the ones you need separately. For mysql just do:\n\n```sh\nnpm install mysql\n```\n\n#### Drivers\n\nDriver | Package\n-------|--------\nmysql  | mysql\n\n#### Driver Registration\n\nIf you want to use another package to access the same database type, you can register the package.\n\n```js\nconst gimlet = require(\"gimlet\");\n\ngimlet.register(\"mysql2\", \"mysql\"); // will use mysql2 package with mysql integration\n\ngimlet.connect(\"mysql2://...\");\n```\n\n### Usage\n\n```js\nconst gimlet = require(\"gimlet\");\nconst db     = gimlet.connect(\"mysql://....\");\n\ndb.handler().query(\"SELECT * FROM users\", (err, users) =\u003e {\n    // this is where the differences from the driver appear\n    console.log(users);\n});\n```\n\n### API\n\n#### Connection\n\nWhen you use `gimlet.connect()` you get a `Connection` instance.\n\n##### handler()\n\nGet a context isolation for possible transactions. This call is synchronous and returns an API to access the database using the connection pool.\n\n###### handler().query(...[, cb])\n\nQuery the database, just like you do with the low level driver. Returned rows should be doped with features.\n\n###### handler().queryRow(...[, cb])\n\nSimilar to `query` but returns only the first row of the results.\n\n###### handler().queryOne(...[, cb])\n\nSimilar to `query` but returns only the first column of the first row of the results.\n\n###### handler().create(table, data[, cb])\n\nJust a shortcut to an INSERT query. `data` should be an object with the properties and values you want.\n\n###### handler().remove(table, conditions[, cb])\n\nJust a shortcut to a DELETE query. `conditions` should be an object.\n\n###### handler().close([cb])\n\nClose connection.\n\n##### open([cb])\n\nOpen connection to database. Some drivers do not connect immediately so you need to call this if you want an immediate connection. MySQL for example connects on first query.\n\n#### Record\n\nWhen calling `connection.query()`, returned rows should be instances of `Record` instead of plain objects. Records usually are extended with some base plugins (and perhaps external plugins). By default, a `Record` will be extended with `record-base`, `record-changes` and `record-freeze` that will give you the methods below.\n\n##### save([changes[, cb]])\n\nSave record modifications. You can pass a `changes` object with a few more changes before saving.\n\n##### remove([cb])\n\nRemove record from database.\n\n##### changes()\n\nReturns an object with the changes detected on the record.\n\n##### changed()\n\nReturns a boolean indicating if the record has been changed or not.\n\n### Special Types\n\nTo simplify the use of `POINT` and `POLYGON` database types, there are special classes to help you. Here's an example.\n\n```js\nconst Gimlet = require(\"gimlet\");\nconst db     = Gimlet.connect(\"mysql://username:password@hostname/database\");\n\ndb.handler().query(\"INSERT INTO locations SET ?\", {\n\tname     : \"Aveiro, Portugal\",\n\tposition : new Gimlet.types.Point(-8.653602, 40.641271),\n})\n```\n\n### Extensions\n\nSome extensions are loaded by default, you can create and load others if you need. The syntax is similar to Express and others.\n\n```js\nconst Gimlet = require(\"gimlet\");\nconst db     = Gimlet.connect(\"test://\");\n\ndb.use(\"cache\"); // use built-in cache extension\ndb.cease(\"record-freeze\"); // stop using built-in record freezing\n```\n\n#### cache\n\nThis is an extension that gives a `Connection` the ability to create simple asynchronous caches.\n\n```js\nconst Gimlet = require(\"gimlet\");\nconst db     = Gimlet.connect(\"mysql://username:password@hostname/database\");\n\ndb.use(\"cache\");\n\nlet userCache = db.cache((id, next) =\u003e {\n    db.handler().queryRow(\"SELECT * FROM users WHERE id = ?\", [ id ], next);\n});\n\n/**\n * This will not trigger 2 queries, only one. The second will queue\n * and wait for the first to return (because the `id` requested is\n * the same).\n **/\nuserCache.get(1, (err, user) =\u003e {\n    console.log(err, user);\n});\nuserCache.get(1, (err, user) =\u003e {\n    console.log(err, user);\n});\n```\n\n#### record-base\n\nThis extensions is the one responsible for creating the `Record.save` and `Record.remove` methods.\n\n#### record-changes\n\nThis extension is the one responsible for creating the `Record.changes` and `Record.changed` methods.\n\n#### record-freeze\n\nThis extension just freezes the object. It just calls `Object.freeze`. This is a special case since, if detected in the extensions list, it will be moved to the end of the load process to avoid freezing objects before all the necessary changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdresende%2Fgimlet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdresende%2Fgimlet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdresende%2Fgimlet/lists"}