PureORM

A pure ORM for writing native SQL queries yielding pure business objects

ORMSQL
craigmichaelmartin/pure-ormpure-orm

README

PureORM


Installation


  1. ``` sh
  2. npm install --save pure-orm
  3. ```

What is PureORM?


PureORM is a lightweight ORM for mapping the relational result rows of a database driver query to properly structured (nested) pure instances of your business object classes.

It's purpose - and guiding principle - is to allow you to write _native_, _unobstructed_ SQL (not niche library-specific ORM wrapper APIs) and receive back properly structured/nested pure business objects (not database-connected stateful objects).

What does this mean?


This means you can just write SQL like this:

  1. ``` js
  2. SELECT *
  3. FROM person
  4. LEFT JOIN job on person.id = job.person_id
  5. LEFT JOIN employer on job.employer_id = employer.id
  6. WHERE person.id = 55
  7. ```

...And for the result data

idnameidpersonIdemployerIdstartDateendDateidname
---------------------------
55John27755172020-01-012020-12-3117Good
55John27855262021-01-012021-12-3126Better

...Rather than getting flat, collided result objects:
  1. ``` js
  2. [
  3.   {
  4.     id: 17, // from employer which collided with job.id and person.id :(
  5.     name: 'Good Corp', // from employer which collided with person.name :(
  6.     person_id: 55,
  7.     employer_id: 17,
  8.     start_date: 2020-01-01T05:00:00.000Z,
  9.     end_date: 2020-12-31T05:00:00.000Z
  10.   },
  11.   {
  12.     id: 26, // from employer which collided with job.id and person.id :(
  13.     name: 'Better Corp', // from employer which collided with person.name :(
  14.     person_id: 55,
  15.     employer_id: 26,
  16.     start_date: 2021-01-01T05:00:00.000Z,
  17.     end_date: 2021-12-31T05:00:00.000Z
  18.   }
  19. ]
  20. ```

...You get properly structured/nested, pure objects like this:

  1. ``` js
  2. {
  3.   id: 55,
  4.   name: "John Doe",
  5.   jobs: {
  6.     models: [
  7.       {
  8.         id: 277,
  9.         personId: 55,
  10.         employerId: 17,
  11.         employer: {
  12.           id: 17,
  13.           name: "Good Corp"
  14.         },
  15.         startDate: "2020-01-01",
  16.         endDate: "2020-12-31"
  17.       },
  18.       {
  19.         id: 278,
  20.         personId: 55,
  21.         employerId: 26,
  22.         employer: {
  23.           id: 26,
  24.           name: "Better Corp"
  25.         },
  26.         startDate: "2021-01-01",
  27.         endDate: "2021-12-31"
  28.       }
  29.     ]
  30.   }
  31. };
  32. ```

...Where these objects are instantiations of classes you define. So the above is our (not shown) Person class, which has a jobs field pointing to our (not shown) Jobs collection class, which has individual (not shown) Job classes, which have a employer field pointing to our (not shown) Employer classes. Each of these classes is defined by us, and can contain custom business logic. (Check out the full example lower down to see these!)

How does PureORM compare with traditional ORMs?


PureORM contrasts with tradtional ORMs in two important ways:

1. PureORM is purely the "orm" (object-relational mapping) - it has the small scope of "owning" the mapping of database driver relational result rows to properly structured business objects. This contrasts against ORMs as typically exist - where they have swelled to intertwine a huge query builder API with the ORM layer, where mapped objects are database-connected and serve as the query builder.
2. PureORM yields pure (not database-connected) models. Queries are written in SQL (not niche library-specific ORM wrapper APIs), and the results are pure businesses objects.

PureORM thus contrasts against traditional ORMs which use query builders (rather than raw SQL) to return database-connected (rather than pure) objects. The name _pureORM_ reflects both of these points - that it is _pure_ ORM (there is no query builder dimension) as well as the _purity_ of the mapped models.

So I bring my own database driver?


Yep! PureORM is the top layer for interfacing with your database. You bring your own database driver (eg node-postgres/pg-promise, mysql, node-sqlite3, node-mssql, node-oracledb, etc), and PureORM works on top of it to perform the Object-Relational Mapping (ORM).

Practical Example


Lets take a practical example to see all this in action. Lets fill in the backend for a tiny rest server for a person.

Lets say we have a database with three tables: person, job, and employer. We want our rest server to return an payload like this for requests which the get method receive.

  1. ```typescript
  2. // app.ts
  3. import express, { Express, Request, Response } from 'express';

  5. const app: Express = express();
  6. const port = process.env.PORT;

  8. app.get('/rest/person', (req: Request, res: Response) => {
  9.   const person = {
  10.     id: 55,
  11.     name: 'John Doe',
  12.     jobs: {
  13.       models: [
  14.         {
  15.           id: 277,
  16.           personId: 55,
  17.           employerId: 17,
  18.           employer: {
  19.             id: 17,
  20.             name: 'Good Corp'
  21.           },
  22.           startDate: '2020-01-01',
  23.           endDate: '2020-12-31'
  24.         },
  25.         {
  26.           id: 278,
  27.           personId: 55,
  28.           employerId: 26,
  29.           employer: {
  30.             id: 26,
  31.             name: 'Better Corp'
  32.           },
  33.           startDate: '2021-01-01',
  34.           endDate: '2021-12-31'
  35.         }
  36.       ]
  37.     }
  38.   };
  39.   res.json(person);
  40. });

  42. app.listen(port);
  43. ```

Based on the tables with this data:

Person
idname
------
55John

Employer
idname
------
17Good
26Better

Job
idpersonIdemployerIdstartDateendDate
---------------|
27755172020-01-012020-12-31
27855262021-01-012021-12-31

I know exactly how I want to query for it:

  1. ```sql
  2. SELECT *
  3. FROM person
  4. LEFT JOIN job on person.id = job.person_id
  5. LEFT JOIN employer on job.employer_id = employer.id
  6. WHERE person.id = 55;
  7. ```

I already know how SQL, and don't want to spend the time mapping what I already know how to do onto a huge, niche, library-specific API.

However, using this query with a database driver would give me a bunch of flat result records (not one object that is properly structed/nested) and with collided fields (id from all three tables, name from person and employer, etc).

So, lets install PureORM and the database driver and get started!

Step 1: Installing PureORM and the Database Driver


For our example, we'll assume postgres database so we'll use the incredible pg-promise database driver.

  1. ``` sh
  2. npm install --save pure-orm
  3. npm install --save pg-promise
  4. ```

Step 2: Creating the Business Objects


Let's create a /models directory, with a file corresponding to each table. These modules contain the model and (optionally) collection classes we want to use when mapping our flat results to business objects, as well as the tableName and columns fields. We'll end up passing all this to the PureORM factory later.

  1. ```typescript
  2. // models/person.ts
  3. import { IModel, ICollection, IColumns, IEntity } from 'pure-orm';

  5. export const tableName: string = 'person';

  7. export const columns: IColumns = ['id', 'name'];

  9. export class Person implements IModel {
  10.   id: number;
  11.   name: string;
  12.   constructor(props) {
  13.     this.id = props.id;
  14.     this.name = props.name;
  15.   }
  16.   // any business methods...
  17. }

  19. export const personEntity: IEntity = { tableName, columns, Model: Person };
  20. ```

  1. ```typescript
  2. // models/job.ts
  3. import { IModel, ICollection, IColumns, IEntity } from 'pure-orm';
  4. import { Person } from './person';
  5. import { Employer } from './employer';

  7. export const tableName: string = 'job';

  9. export const columns: IColumns = [
  10.   'id',
  11.   { column: 'person_id', references: Person },
  12.   { column: 'employer_id', references: Employer },
  13.   'start_date',
  14.   'end_date'
  15. ];

  17. export class Job implements IModel {
  18.   id: number;
  19.   personId: number;
  20.   person?: Person;
  21.   employerId: number;
  22.   employer: Employer;
  23.   startDate: Date;
  24.   endDate: Date;
  25.   constructor(props) {
  26.     this.id = props.id;
  27.     this.personId = props.personId;
  28.     this.person = props.person;
  29.     this.employerId = props.employerId;
  30.     this.employer = props.employer;
  31.     this.startDate = props.startDate;
  32.     this.endDate = props.endDate;
  33.   }
  34.   // any business methods...
  35. }

  37. export const JobEntity: IEntity = { tableName, columns, Model: Job };
  38. ```

  1. ```typescript
  2. // models/employer.ts
  3. import { IModel, ICollection, IColumns, IEntity } from 'pure-orm';

  5. export const tableName: string = 'employer';

  7. export const columns: IColumns = ['id', 'name'];

  9. export class Employer implements IModel {
  10.   id: number;
  11.   name: string;
  12.   constructor(props: IEmployerProps) {
  13.     this.id = props.id;
  14.     this.name = props.name;
  15.   }
  16.   // any business methods...
  17. }

  19. export const EmployerEntity: IEntity = { tableName, columns, Model: Employer };
  20. ```

Step 3: Creating our ORM


First we create our database driver:

  1. ```typescript
  2. // ./factories/db.ts
  3. import pgPromise from 'pg-promise';
  4. const pgp = pgPromise();
  5. const connectionObject = {
  6.   host: process.env.DB_HOSTNAME,
  7.   port: process.env.DB_PORT,
  8.   database: process.env.DB_NAME,
  9.   user: process.env.DB_USERNAME,
  10.   password: process.env.DB_PASSWORD
  11. };
  12. export const db = pgp(connectionObject);
  13. ```

We can now create our ORM, which layers atop the database driver to do the object relational mapping of raw sql row data to nest objects. (Besides using the db instance directly, the orm also offers access to the db directly (orm.db) for anytime this object relational mapping isn't desired.

  1. ```typescript
  2. // factories/orm.ts
  3. import { create } from 'pure-orm';
  4. import { db } from './db';
  5. import { personEntity } from '../models/person';
  6. import { jobEntity } from '../models/job';
  7. import { employerEntity } from '../models/employer';
  8. const orm = create({
  9.   entities: [personEntity, jobEntity, employerEntity],
  10.   db
  11. });
  12. export default orm;
  13. ```

Step 4: Creating our Data Access Layer


Let's now create a data access directory with a person file for data access operations related to a person.

  1. ```typescript
  2. // data-access/person.ts
  3. import orm from '../factories/orm';
  4. import { Person } from '../models/person';

  6. export const getPerson = (id: number): Person => {
  7.   const query = `
  8.     SELECT
  9.       ${orm.tables.person.columns},
  10.       ${orm.tables.job.columns},
  11.       ${orm.tables.employer.columns}
  12.     FROM person
  13.     LEFT JOIN job on person.id = job.person_id
  14.     LEFT JOIN employer on job.employer_id = employer.id
  15.     WHERE id = $(id)
  16.   `;
  17.   return orm.one(query, { id });
  18. };
  19. ```

Some things to note:

- Our data access function returns a single Person model which is properly structured from the many relational row records!
- Our query is executed with a one method. The ORM methods for one, oneOrNone, many, any ensure their count against the number of generated top level models - not the number of relational row records the sql expression returns!
- Rather than manually specifying our columns in the sql select expression, we used the orm's getter for columns. This is purely a convenience method which namespaces each column with the table name prefix to ensure column names don't collide (for example, the person, job, and employer ids would collide if not namespaced, as would person and employer names). You are welcome to do this by hand instead of using this convenience if you don't mind the tedium:

  1. ```typescript
  2.   // data-access/person.ts
  3.   import orm from '../factories/orm';
  4.   import { Person } from '../models/person';

  6.   const getPerson(id) {
  7.     // Example showing you can manually specify the select expression fields
  8.     // instead of using the orm's columns getter.
  9.     // Note: you must namespace the field with table name and hashtag.
  10.     const query = `
  11.       SELECT
  12.         person.id as "person#id",
  13.         person.name as "person#name",
  14.         job.id as "job#id",
  15.         job.person_id as "job#person_id",
  16.         job.employer_id as "job#employer_id",
  17.         job.start_date as "job#start_date",
  18.         job.end_date as "job#end_date",
  19.         employer.id as "employer#id",
  20.         employer.name as "employer#name"
  21.       FROM person
  22.       LEFT JOIN job on person.id = job.person_id
  23.       LEFT JOIN employer on job.employer_id = employer.id
  24.       WHERE id = $(id)
  25.     `;
  26.     return orm.one(query, { id });
  27.   }
  28.   module.exports = getPerson;
  29. ```

Step 5: Writing the Controller Code


We can now return to our controller code, and use our data access function.

  1. ```diff
  2. // app.ts
  3. import express, { Express, Request, Response } from 'express';
  4. +import { getPerson } from './data-access/person';

  6. const app: Express = express();
  7. const port = process.env.PORT;

  9. app.get('/rest/person', (req: Request, res: Response) => {
  10. - const person = {
  11. -   id: 55,
  12. -   name: 'John Doe',
  13. -   jobs: {
  14. -     models: [
  15. -       {
  16. -         id: 277,
  17. -         personId: 55,
  18. -         employerId: 17,
  19. -         employer: {
  20. -           id: 17,
  21. -           name: 'Good Corp'
  22. -         },
  23. -         startDate: '2020-01-01',
  24. -         endDate: '2020-12-31'
  25. -       },
  26. -       {
  27. -         id: 278,
  28. -         personId: 55,
  29. -         employerId: 26,
  30. -         employer: {
  31. -           id: 26,
  32. -           name: 'Better Corp'
  33. -         },
  34. -         startDate: '2021-01-01',
  35. -         endDate: '2021-12-31'
  36. -       }
  37. -     ]
  38. -   }
  39. - };
  40. + const person = getPerson(req.params.id);
  41.   res.json(person);
  42. });

  44. app.listen(port);
  45. ```

That's it! This controller code now works! The getPerson function returns a properly structured business object as we desire.

API


create


  1. ```typescript
  2. function create(options: {
  3.   entities: Array<IEntity>;
  4.   db: DataBaseDriver;
  5. }): PureORM;
  6. ```

The factory function for creating your ORM.

Parameters

- `entities: Array` - An array of all the business object class entity configuration objects.

  1. ```typescript
  2.   interface IEntity<T extends IModel> {
  3.     // the tablename in the database for the entity (EG: article_tag)
  4.     tableName: string;
  5.     // the name to use for the model in the structured results of other models
  6.     // defaults to the camelcase of the tableName (EG: articleTag)
  7.     displayName?: string;
  8.     // the name to use for the collection in the structured results of other models
  9.     // defaults to adding an "s" to the displayName (EG: articleTags)
  10.     collectionDisplayName?: string;
  11.     // the column specs for the table (see interferface below)
  12.     columns: IColumns;
  13.     // the pure business object to use for result data
  14.     Model: new (props: any) => T;
  15.     // the pure business object to use for result collection data
  16.     Collection: new ({ models }: any) => ICollection<T>;
  17.   }

  19.   // the interface for the `columns` property of the Entity interface.
  20.   // is usually an array of the column data, but can be a function which
  21.   // returns they array of column data (which is used to avoid circular
  22.   // dependency issues when two entities reference each other).
  23.   type IColumns = Array<IColumn> | (() => Array<IColumn>);

  25.   // the column can just be a string (EG: 'id', 'value, 'label') which is
  26.   // understood to be the column name, or it can be an IColumnData object.
  27.   type IColumn = string | IColumnData;

  29.   // an object to specify more than just the column name
  30.   interface IColumnData {
  31.     // the name of the column (EG: is_active)
  32.     column: string;
  33.     // the name to be used in the pure business object model
  34.     // (defaults to the camelcase of the column, EG: isActive)
  35.     property?: string;
  36.     // the model this column references as a foreign key
  37.     references?: new (props: any) => IModel;
  38.     // whether this column is a primary key
  39.     primaryKey?: boolean;
  40.   }
  41. ```

- `db: ` - A database driver instance.

Return Value

Your PureORM instance, which is of this interface:

  1. ```typescript
  2. interface PureORM {
  3.   /* ------------------------------------------------------------------------*/
  4.   /* Query methods ----------------------------------------------------------*/
  5.   /* ------------------------------------------------------------------------*/

  7.   /* Note these query methods ensure their count against the number of
  8.    * generated top level business objects which are created - not the number
  9.    * of relational rows returned from the database driver! Thus, for example,
  10.    * `one` understands that there may be multiple result rows (which a
  11.    * database driver's `one` query method would throw at) but which correctly
  12.    * nest into one Model.)
  13.    */

  15.   // Execute a query returning a single model, or throws.
  16.   one: <T extends IModel>(
  17.     query: string,
  18.     values?: object,
  19.     errorHandler?: (err: Error) => never
  20.   ) => T;

  22.   // Execute a query returning either single model or undefined, or throws.
  23.   oneOrNone: <T extends IModel>(
  24.     query: string,
  25.     values?: object,
  26.     errorHandler?: (err: Error) => never
  27.   ) => T | void;

  29.   // Execute a query returning a Collection with at least one model, or throws.
  30.   many: <T extends ICollection<IModel>>(
  31.     query: string,
  32.     values?: object,
  33.     errorHandler?: (err: Error) => never
  34.   ) => T;

  36.   // Execute a query returning a Collection.
  37.   any: <T extends ICollection<IModel>>(
  38.     query: string,
  39.     values?: object,
  40.     errorHandler?: (err: Error) => never
  41.   ) => T | void;

  43.   // Execute a query returning null.
  44.   none: (
  45.     query: string,
  46.     values?: object,
  47.     errorHandler?: (err: Error) => never
  48.   ) => void;

  50.   /* ------------------------------------------------------------------------*/
  51.   /* Built-in basic CRUD functions ------------------------------------------*/
  52.   /* ------------------------------------------------------------------------*/

  54.   /* These are just provided because they are so common and straight-forward.
  55.    * While the goal of this library is foster writing SQL in your data access
  56.    * layer (which returns pure business objects) some CRUD operations are so
  57.    * common they are included in the ORM. Feel free to completely disregard
  58.    * if you want to write these in your data access layer yourself.
  59.    */

  61.   getMatching: <T extends IModel>(model: T) => T;
  62.   getOneOrNoneMatching: <T extends IModel>(model: T) => T | void;
  63.   getAnyMatching: <T extends ICollection<IModel>>(model: IModel) => T | void;
  64.   getAllMatching: <T extends ICollection<IModel>>(model: IModel) => T;
  65.   create: <T extends IModel>(model: T) => T;
  66.   update: <T extends IModel>(model: T, options: { on: string }) => T;
  67.   delete: <T extends IModel>(model: T) => void;
  68.   deleteMatching: <T extends IModel>(model: T) => void;

  70.   /* ------------------------------------------------------------------------*/
  71.   /* Helpful Properties -----------------------------------------------------*/
  72.   /* ------------------------------------------------------------------------*/

  74.   /* The tables property gives access to the sql select clause string for
  75.    * each entity based on it's `displayName`. This property can be used when
  76.    * writing raw SQL as the select clause, which handles quoting column names
  77.    * and namespacing them to the table to avoid collisions and as required
  78.    * for PureORM mapping.
  79.    */
  80.   tables: { [key: string]: { columns: string } };
  81.   db: DataBaseDriver;
  82. }
  83. ```

FAQ


Can you show the business objects of a more complex entity?


  1. ```typescript
  2. import { IModel, ICollection, IColumns, IEntity } from 'pure-orm';

  4. export const tableName: string = 'library_v2';

  6. export const columns: IColumns = [
  7.   'id',
  8.   'name',
  9.   { column: 'is_ala_member', property: 'isALAMember' },
  10.   { column: 'address_id', references: Address }
  11. ];

  13. export const displayName = 'library';
  14. export const collectionDisplayName = 'libraries';

  16. interface ILibraryProps {
  17.   id: number;
  18.   name: string;
  19.   isALAMember: string;
  20.   addressId: number;
  21.   address: Address;
  22. }

  24. export class Library implements IModel {
  25.   id: number;
  26.   name: string;
  27.   constructor(props: ILibraryProps) {
  28.     this.id = props.id;
  29.     this.name = props.name;
  30.     this.isALAMember = props.isALAMember;
  31.     this.addressId = props.addressId;
  32.     this.address = props.address;
  33.   }
  34.   aBussinessObjectMethod() {}
  35.   anotherBussinessObjectMethod() {}
  36. }

  38. export class Persons implements ICollection<Person> {
  39.   models: Array<Person>;
  40.   constructor({ models }: any) {
  41.     this.models = models;
  42.     return this;
  43.   }
  44.   aCollectionMethod() {}
  45.   anotherCollectionMethod() {}
  46. }

  48. export const personEntity: IEntity = {
  49.   tableName,
  50.   displayName,
  51.   collectionDisplayName,
  52.   columns,
  53.   Model: Person,
  54.   Collection: Persons
  55. };
  56. ```

If I use PureORM do I have to re-invent all the super basic CRUD methods?


The goal of PureORM is to foster writing SQL and receiving pure business objects. That said, some SQL is so common that we preload the created ORM with with some basic CRUD operations.

For example, rather than every entity needing data access operatons for get, create, etc method, you can use built-in orm functions.

  1. ```typescript
  2. app.get('/rest/person', (req: Request, res: Response) => {
  3.   if (req.params.id) {
  4.     return res.json(await orm.getMatching(new Person({ id })));
  5.   }
  6.   if (req.query.name) {
  7.     return res.json(
  8.       await orm.getAnyMatching(new Person({ name: req.query.name }))
  9.     );
  10.   }
  11.   res
  12.     .status(404)
  13.     .json({ error: 'Please specify an id or provide a name filter' });
  14. };
  15. ```

At any point you can ditch these built-ins and write some SQL in a data access function.

  1. ```typescript
  2. import { getPerson, getPeopleWithName } from '../../data-access/person';

  4. app.get('/rest/person', (req: Request, res: Response) => {
  5.   if (req.params.id) {
  6.     return res.json(await getPerson(id));
  7.   }
  8.   if (req.query.name) {
  9.     return res.json(await getPeopleWithName(req.query.name));
  10.   }
  11.   res
  12.     .status(404)
  13.     .json({ error: 'Please specify an id or provide a name filter' });
  14. };
  15. ```

Whare are the tradeoffs that PureORM makes in using SQL instead of a query builder API?


Traditional/stateful ORMs offer a dialetic-generic, chainable object api for expressing underlying SQL - thus solving for database "lock-in" as well the inability of string queries compose easily. PureORM takes the approach that the tradeoff of developers having to learn the huge surface area of of a query builder, and having to map the complexity and nuance of SQL to it, are simply not worth the cost, and so is premised on not using a query building library. PureORM sees writing straight SQL heaviliy as a feature, not a defect needing solved, and not eclipsed by the composibility of a query builder.

Will I then have dozens of similar data access functions, since strings aren't as composable as stateful ORM builder builder APIs?


There is still a lot of composibility possible with functions returning strings (someone create an Issue if you want to see examples used in the Kujo codebase), but in general yes, there is more repitition. Most of this remaining repitition is not something I think is a defect (though those obsessed with DRY would disagree).

Does PureORM abstract away the database driver?


No, the whole premise of PureORM is to offer a library to aid the use of writing SQL. The datebase driver is always available to you (at orm.db) if you wish to use it directly with no PureORM mappings, or just import it. In my experience, a small percentage of highly complex queries looking for sums or counts in my data access layer use the database driver directly.

The only difference is how the SQL is invoked: orm.one(query, {}) vs orm.db.one(query, {})

Can I use aggregate functions while still using the PureORM mapping?


Yes, if you'd like to get the mapping while also passing through some select expressions, use the special meta prefix. For example:

  1. ``` js
  2. const getBloggerPayout = ({ id, startDate, endDate }) => {
  3.   const query = `
  4.     SELECT
  5.       ${orm.tables.person.columns},
  6.       COALESCE(SUM(article.blogger_payout), 0) as meta_amount
  7.     FROM
  8.       person
  9.     LEFT JOIN article
  10.       ON article.author_id = person.id
  11.       AND (article.created_date BETWEEN $(startDate) AND $(endDate))
  12.     WHERE
  13.       person.id = $(id)
  14.     GROUP BY person.id, person.slug, person.email,
  15.       person.first_name, person.last_name, person.last_paid_date,
  16.       person.pay_frequency
  17.     ORDER BY meta_amount DESC NULLS LAST;
  18.   `;
  19.   return orm.one(query, { id, startDate, endDate });
  20. };
  21. ```

Comparisons


Low Level Abstractions

- Database Drivers (eg node-postgres, mysql, node-sqlite3, node-mssql, node-oracledb) - These are powerful low level libraries that handle connecting to a database, executing raw SQL, and returning raw rows. All the higher level abstractions are built on these.PureORM like "stateful ORMs" are built on these.

Stateful ORMs (comprised of two portions)

- Query Builders (eg knex) - These (built on database drivers) offer a dialetic-generic, chainable object api for expressing underlying SQL - thus solving for database "lock-in" as well the inability to compose SQL queriers as strings. PureORM takes the approach that the tradeoff of developers having to learn the huge surface area of dialetic-generic api, and having to map the complexity and nuance of SQL to it, are simply not worth the cost, and so does not use a query building library. With PureORM you just write SQL. The tradeoff on PureORM side that is indeed being tied to a sql dialect and in the inability to compose sql expressions (strings don't compose nicely). Yet all this considered, PureORM sees writing straight SQL heaviliy as a feature, not a defect needing solved, and not eclipsed by the composibility of a query builder.

- Stateful, Database Aware Objects (eg sequelize, waterline, bookshelf, typeorm) - These stateful, database-aware object libraries are the full embrace of "Stateful ORMs". Contrary to this these is PureORM which yields pure, un-attached, structured objects.

PureORM

- PureORM is more than just the preference against the query builder portion of Stateful ORMs
- PureORM is the preference against stateful, db-connected objects: PureORM resolves result rows to _pure_ business objects. This purity in business objects fosters a clean layer of the business layer from the data access layer, as well as ensuring the very best in performance (eg, the N+1 problem can't exist with pure objects).

Current Status


Current Todos (PRs welcome!):


- Performance. While the API has been somewhat thought through and iterated on to this point, the implementation details have been secondary, knowing that they can be perfected in time. Probably about time now.
- Add more tests
- Known Bug: if a table references the same table twice, the first one is found as the nodePointingToIt and so ends up throwing.
  - ideally the fix to this will change the behavior of when a table points to another table by another name (author_id -> person)

Is it production ready?


It is in production at www.kujo.com - powering the marketing pages and blog, as well as the customer, affiliate, and admin platforms (behind login). When considering for your case, note the Current Limitations and TODOs sections above.