# leoric > yet another JavaScript object-relational mapping library Latest version **2.16.0** (published 2026-08-18) · BSD-3-Clause license · 0 weekly downloads ## Install ```sh npm install leoric pnpm add leoric yarn add leoric bun add leoric ``` ## Health **Score 75/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 2.16.0 | | Published | 2026-08-18 | | First published | 2017-12-09 | | Weekly downloads | 0 | | License | BSD-3-Clause | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >= 18.0.0 | | Dependencies | 8 | | Unpacked size | 1.6 MB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 234 | | Maintainers | dotnil, jimmydaddy | | Keywords | model, mysql, orm, postgresql, query builder, sqlite | ## Links - npm: https://www.npmjs.com/package/leoric - Repository: https://github.com/cyjake/leoric - Homepage: https://github.com/cyjake/leoric#readme - Issues: https://github.com/cyjake/leoric/issues - npm.io page: https://npm.io/package/leoric ## Dependencies (8) - [dayjs](https://npm.io/package/dayjs.md) ^1.10.3 - [debug](https://npm.io/package/debug.md) ^3.1.0 - [tslib](https://npm.io/package/tslib.md) ^2.5.0 - [pluralize](https://npm.io/package/pluralize.md) ^7.0.0 - [sqlstring](https://npm.io/package/sqlstring.md) ^2.3.0 - [validator](https://npm.io/package/validator.md) ^13.5.2 - [deep-equal](https://npm.io/package/deep-equal.md) ^2.0.5 - [reflect-metadata](https://npm.io/package/reflect-metadata.md) ^0.1.13 ## Alternatives - [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads - [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads - [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads - [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads - [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads ## Recent versions - 2.16.0 (latest) — 2026-08-18 - 2.15.0-beta.5 (beta) — 2026-08-06 - 2.15.0-alpha.4 (alpha) — 2026-03-26 - 2.15.0 — 2026-08-10 - 2.15.0-beta.4 — 2026-08-06 - 2.15.0-beta.3 — 2026-07-27 - 2.15.0-beta.2 — 2026-07-21 - 2.15.0-beta.1 — 2026-07-20 - 2.15.0-alpha.3 — 2026-03-19 - 2.15.0-alpha.2 — 2026-03-06 - 2.15.0-alpha.1 — 2026-03-05 - 2.15.0-alpha.0 — 2026-02-26 - 2.14.0 — 2025-12-09 - 2.13.9 — 2025-10-21 - 2.13.8 — 2025-09-16 - … 146 more at https://npm.io/package/leoric/versions ## README # Leoric [![Package Quality](https://packagequality.com/shield/leoric.svg)](https://packagequality.com/#?package=leoric) [![NPM Downloads](https://img.shields.io/npm/dm/leoric.svg?style=flat)](https://www.npmjs.com/package/leoric) [![NPM Version](http://img.shields.io/npm/v/leoric.svg?style=flat)](https://www.npmjs.com/package/leoric) [![Build Status](https://github.com/cyjake/leoric/actions/workflows/nodejs.yml/badge.svg)](https://github.com/cyjake/leoric/actions/workflows/nodejs.yml) [![codecov](https://codecov.io/gh/cyjake/leoric/branch/master/graph/badge.svg?token=OZZWTZTDS1)](https://codecov.io/gh/cyjake/leoric) Leoric is an object-relational mapping library for Node.js, which is heavily influenced by Active Record of Ruby on Rails. See the [documentation](https://leoric.js.org) for detail. ## Usage Assume the tables of posts, users, and comments were setup already. We may declare the models as classes by extending from the base class `Bone` of Leoric. After the models are connected to the database, the columns of the tables are mapped as attributes, the associations are setup, feel free to start querying. ```js import Realm, { Bone } from 'leoric' const realm = new Realm({ host: 'example.com' }) const Post = realm.define(class Post extends Bone { static initialize() { this.belongsTo('author', { Model: 'User' }) this.hasMany('comments') } }) async function main() { // connect models to database await realm.connect() // CRUD await Post.create({ title: 'New Post' }) const post = await Post.findOne({ title: 'New Post' }) post.title = 'Untitled' await post.save() // or UPDATE directly await Post.update({ title: 'Untitled' }, { title: 'New Post' }) // find with associations const post = await Post.findOne({ title: 'New Post' }).with('comments') console.log(post.comments) // => [ Comment { id, content }, ... ] } ``` If table structures were intended to be maintained in the models, Leoric can be used as a table migration tool as well. We can just define attributes in the models, and call `realm.sync()` whenever we are ready. ```js import Realm, { Bone, DataTypes } from 'leoric'; const { BIGINT, STRING } = DataTypes; const realm = new Realm(); const Post = realm.define(class Post extends Bone { static attributes = { id: { type: BIGINT, primaryKey: true }, email: { type: STRING, allowNull: false }, nickname: { type: STRING, allowNull: false }, } }); await realm.sync(); ``` ## Syntax Table | JavaScript | SQL | |-----------------------------------------|----------------------------------------------------| | `Post.create({ title: 'New Post' })` | `INSERT INTO posts (title) VALUES ('New Post')` | | `Post.all` | `SELECT * FROM posts` | | `Post.find({ title: 'New Post' })` | `SELECT * FROM posts WHERE title = 'New Post'` | | `Post.find(42)` | `SELECT * FROM posts WHERE id = 42` | | `Post.order('title')` | `SELECT * FROM posts ORDER BY title` | | `Post.order('title', 'desc')` | `SELECT * FROM posts ORDER BY title DESC` | | `Post.limit(20)` | `SELECT * FROM posts LIMIT 0, 20` | | `Post.update({ id: 42 }, { title: 'Skeleton King' })` | `UPDATE posts SET title = 'Skeleton King' WHERE id = 42` | | `Post.remove({ id: 42 })` | `DELETE FROM posts WHERE id = 42` | A more detailed syntax table may be found at the [documentation](https://leoric.js.org/#syntax-table) site. ## TypeScript charged ```ts import { Bone, BelongsTo, Column, DataTypes: { TEXT } } from 'leoric'; import User from './user'; export default class Post extends Bone { @Column({ autoIncrement: true }) declare id: bigint; @Column(TEXT) declare content: string; @Column() declare description: string; @Column() declare userId: bigint; @BelongsTo() declare user: User; } ``` More about TypeScript integration examples can be found at [the TypeScript support documentation](https://leoric.js.org/types) ## AI-Friendly Resources Leoric is designed to work well with AI coding assistants, both for end users and for contributors: - [AI Cookbook](https://leoric.js.org/ai-cookbook) (中文：[AI 代码手册](https://leoric.js.org/zh/ai-cookbook)) — copy-pasteable, verified patterns for models, queries, transactions, and troubleshooting - [llms.txt](https://leoric.js.org/llms.txt) — machine-readable index of the documentation - [llms-full.txt](https://leoric.js.org/llms-full.txt) / [llms-full-zh.txt](https://leoric.js.org/llms-full-zh.txt) — all guides concatenated for single-shot context injection - These files are also shipped inside the npm package (`node_modules/leoric/llms-full.txt` etc.), so AI assistants in offline or private-registry environments can still read the full documentation - [AGENTS.md](./AGENTS.md) (中文版：[AGENTS.zh-CN.md](./AGENTS.zh-CN.md)) — repository guide for AI agents and contributors - Public API types ship with JSDoc, so IDE autocompletion and AI code generation see documented signatures out of the box ## Contributing There are many ways in which you can participate in the project, for example: - [Submit bugs and feature requests](https://github.com/cyjake/leoric/issues), and help us verify as they are checked in - [Review source code changes](https://github.com/cyjake/leoric/pulls) - Review the [documentation](https://leoric.js.org) and make pull requests for anything from typo to new content If you are interested in fixing issues and contributing directly to the code base, please see the document [How to Contribute](https://leoric.js.org/contributing/guides), which covers the following: - The development workflow, including debugging and running tests - Coding guidelines - Submitting pull requests - Contributing to translations ## egg-orm If developing web applications with [egg framework](https://eggjs.org/), it's highly recommended using the [egg-orm](https://github.com/eggjs/egg-orm) plugin. More detailed examples about setting up egg-orm with egg framework in either JavaScript or TypeScript can be found at ## mysql nuances macOS binds localhost to ipv6 `::1`, yet both mysql and mysql2 connect database with localhost by default, which means both will try connecting to mysql with `::1`. However, the mysql distribution installed with HomeBrew sets `bind_address = 127.0.0.1`, hence causes following error: ```js Error: connect ECONNREFUSED ::1:3306 at __node_internal_captureLargerStackTrace (node:internal/errors:490:5) at __node_internal_exceptionWithHostPort (node:internal/errors:668:12) at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1494:16) ``` Please change the configuration as below: ```diff diff --git a/usr/local/etc/my.cnf b/usr/local/etc/my.cnf index 7218354..d31859c 100644 --- a/usr/local/etc/my.cnf +++ b/usr/local/etc/my.cnf @@ -1,5 +1,5 @@ # Default Homebrew MySQL server config [mysqld] # Only allow connections from localhost -bind-address = 127.0.0.1 +bind-address = 127.0.0.1,::1 mysqlx-bind-address = 127.0.0.1 ``` and restart the mysql service: ```bash brew services mysql restart ``` --- _Source: https://npm.io/package/leoric · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._