leoric AGENTS.md

Agent Guidelines

This file guides AI coding agents working in the leoric repository. Read it before making changes: it captures conventions that are not obvious from the code alone. A Chinese mirror is available in AGENTS.zh-CN.md.

Project Overview

Leoric is an object-relational mapping (ORM) library for Node.js, heavily influenced by Active Record of Ruby on Rails. Models are declared as classes extending Bone, connected to MySQL/PostgreSQL/SQLite through Realm, and queried with a chainable API. Source is TypeScript (src/); tsc emits JavaScript (lib/ for CJS, dist/ for ESM) plus declaration files (lib/*.d.ts), which ship to npm.

Commands

Command	Purpose
npm run prepack	Build lib/ (CJS) and declaration files; also builds ts4.9-compatible types via scripts/build-ts49-types.js
npm run prepack:browser	Build the ESM bundle in dist/
npm run test:sqlite	Fastest test run (single dialect, runs through test/start.sh)
npm run test:unit	Unit tests only
npm run test	Full suite: unit first, then integration per dialect
npm run test:dts	Type-level tests in test/types/*.test.ts (consumer fixtures: test:dts:ts5, test:dts:ts4.9)
npm run lint	ESLint over the whole repo
npm run jsdoc	Regenerate docs/api from JSDoc comments

Notes:

• Tests run via mocha + ts-node through test/start.sh; no build step is needed before testing.
• Integration tests need databases on localhost; check test/prepare.sh and test/start.sh for how they are provisioned.
• lib/ and dist/ are build artifacts — never edit them directly; regenerate with npm run prepack.

Architecture

• src/bone.ts — the Bone base class users extend; typed query entry points (find, findOne, sum, restore, update...)
• src/abstract_bone.ts — core model implementation: attributes, associations, lifecycle, init()/sync(), instance methods (save, remove, reload, toObject...)
• src/model.ts — model class compilation (compileModel) and LeoricModelCompilationError
• src/realm/base.ts — Realm: connection management, define(), model registration, connect()/sync()/query()/transaction()
• src/drivers/ — SQL dialects (mysql, postgres, sqlite, sqljs) built on drivers/abstract
• src/spell.ts — the chainable query builder (where, order, limit, with, ...); turns into SQL via src/expr.ts / src/expr_formatter.ts
• src/query_object.ts — condition parsing (operators such as $gt, $in) consumed by spell
• src/data_types.ts — DataTypes definitions
• src/adapters/sequelize.ts — Sequelize compatibility layer
• src/index.ts — public entry; re-exports everything users import from leoric