pure-orm 4.0.0 → 4.0.2

package/README.md

@@ -10,43 +10,99 @@ npm install --save pure-orm
 
 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 regular native SQL (not niche library-specific ORM wrapper APIs) and receive back properly structured/nested pure business objects (not database-connected stateful objects).
+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).
 
-PureORM is the top layer for interfacing with your database. You bring your own database driver (eg [node-postgres](https://github.com/brianc/node-postgres)/[pg-promise](https://github.com/vitaly-t/pg-promise), [mysql](https://github.com/mysqljs/mysql), [node-sqlite3](https://github.com/mapbox/node-sqlite3), [node-mssql](https://github.com/tediousjs/node-mssql), [node-oracledb](https://github.com/oracle/node-oracledb), etc), and PureORM works on top of it to perform the Object-Relational Mapping (ORM).
+#### What does this mean?
 
-PureORM contrasts with tradtional ORMs in two ways:
+This means you can just write SQL like this:
 
-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 "ORM"s as typically exist - where they have grown 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) business objects. Queries are written in SQL (not niche library-specific ORM wrapper APIs), and the results are pure businesses objects.
+```javascript
+SELECT *
+FROM person
+LEFT JOIN job on person.id = job.person_id
+LEFT JOIN employer on job.employer_id = employer.id
+WHERE person.id = 55
+```
 
-Thus PureORM contrasts against traditional ORMs which use query builders (rather than raw SQL) to return database-connected (rather than pure) objects.
+...And for the result data
 
-The name _**pure**ORM_ reflects both of these points - that it is _pure_ ORM (there is no query builder dimension) as well as the _purity_ of the mapped objects.
+| id  | name     | id  | personId | employerId | startDate  | endDate    | id  | name        |
+| --- | -------- | --- | -------- | ---------- | ---------- | ---------- | --- | ----------- |
+| 55  | John Doe | 277 | 55       | 17         | 2020-01-01 | 2020-12-31 | 17  | Good Corp   |
+| 55  | John Doe | 278 | 55       | 26         | 2021-01-01 | 2021-12-31 | 26  | Better Corp |
 
-#### Philosophy
+...Rather than getting flat, collided result objects:
 
-- Write _native_, _unobstructed_ SQL in a "data access layer" which returns _pure_ "business objects" to be used in the app's business logic.
+```javascript
+[
+  {
+    id: 17, // from employer which collided with job.id and person.id :(
+    name: 'Good Corp', // from employer which collided with person.name :(
+    person_id: 55,
+    employer_id: 17,
+    start_date: 2020-01-01T05:00:00.000Z,
+    end_date: 2020-12-31T05:00:00.000Z
+  },
+  {
+    id: 26, // from employer which collided with job.id and person.id :(
+    name: 'Better Corp', // from employer which collided with person.name :(
+    person_id: 55,
+    employer_id: 26,
+    start_date: 2021-01-01T05:00:00.000Z,
+    end_date: 2021-12-31T05:00:00.000Z
+  }
+]
+```
+
+...You get properly structured/nested, pure objects like this:
+
+```javascript
+{
+  id: 55,
+  name: "John Doe",
+  jobs: {
+    models: [
+      {
+        id: 277,
+        personId: 55,
+        employerId: 17,
+        employer: {
+          id: 17,
+          name: "Good Corp"
+        },
+        startDate: "2020-01-01",
+        endDate: "2020-12-31"
+      },
+      {
+        id: 278,
+        personId: 55,
+        employerId: 26,
+        employer: {
+          id: 26,
+          name: "Better Corp"
+        },
+        startDate: "2021-01-01",
+        endDate: "2021-12-31"
+      }
+    ]
+  }
+};
+```
 
-#### Concepts
+...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!)
 
-A **Model** is a pure javascript business object corresponding to a table.
+#### How does PureORM compare with traditional ORMs?
 
-- In PureORM these pure business objects are referred to as "models".
-- They represent a row of the table data, but as pure javascript objects.
-- They are not connected to the database.
-- They are the subject of the app's business logic.
-- They will be full of userland business logic methods.
-- Their purity allows them to be easy to test/use.
+PureORM contrasts with tradtional ORMs in two important ways:
 
-A **Collection** is a pure business object with a reference to a group of models.
+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.
 
-- If your query returns records for multiple models, a Collection will be created and returned.
-- You can create the Collection class (in cases where it is useful to have business methods on the collection object, not just each model object).
+PureORM thus contrasts against traditional ORMs which use query builders (rather than raw SQL) to return database-connected (rather than pure) objects. The name _**pure**ORM_ 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.
 
-A **Data Access Layer** is a database-aware abstraction layer where native SQL is written, and which returns pure business objects.
+#### So I bring my own database driver?
 
-- With PureORM, database-aware code is limited to a data access layer. Your higher up controller and service layers deal only with API calls to the Data Access functions, which are written with native SQL, and which returns pure business objects.
-- There are no database-bound stateful orm objects with their huge query builder APIs sprawling across all the application code. Instead there is a single layer where native SQL is written, and which returns pure business objects (properly nested and structured).
+Yep! PureORM is the top layer for interfacing with your database. You bring your own database driver (eg [node-postgres](https://github.com/brianc/node-postgres)/[pg-promise](https://github.com/vitaly-t/pg-promise), [mysql](https://github.com/mysqljs/mysql), [node-sqlite3](https://github.com/mapbox/node-sqlite3), [node-mssql](https://github.com/tediousjs/node-mssql), [node-oracledb](https://github.com/oracle/node-oracledb), etc), and PureORM works on top of it to perform the Object-Relational Mapping (ORM).
 
 ## Practical Example
 
@@ -71,23 +127,23 @@ app.get('/rest/person', (req: Request, res: Response) => {
           id: 277,
           personId: 55,
           employerId: 17,
-          startDate: '2020-01-01',
-          endDate: '2020-12-31',
           employer: {
             id: 17,
             name: 'Good Corp'
-          }
+          },
+          startDate: '2020-01-01',
+          endDate: '2020-12-31'
         },
         {
           id: 278,
           personId: 55,
           employerId: 26,
-          startDate: '2021-01-01',
-          endDate: '2021-12-31',
           employer: {
             id: 26,
             name: 'Better Corp'
-          }
+          },
+          startDate: '2021-01-01',
+          endDate: '2021-12-31'
         }
       ]
     }
@@ -144,7 +200,7 @@ npm install --save pg-promise
 
 ### Step 2: Creating the Business Objects
 
-Let's create a `/models` directory of business object classes for our database tables. These classes need to implement a static getter for `tableName` and `sqlColumnsData` to denote the database table and columns.
+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.
 
 ```typescript
 // models/person.ts
@@ -227,8 +283,6 @@ export class Employer implements IModel {
 export const EmployerEntity: IEntity = { tableName, columns, Model: Employer };
 ```
 
-We've not got our three entities that relate our table data to our business objects.
-
 ### Step 3: Creating our ORM
 
 First we create our database driver:
@@ -307,10 +361,10 @@ Some things to note:
         person.id as "person#id",
         person.name as "person#name",
         job.id as "job#id",
-        job.person_id: "job#person_id",
-        job.employer_id: "job#employer_id",
-        job.start_date: "job#start_date",
-        job.end_date: "job#end_date",
+        job.person_id as "job#person_id",
+        job.employer_id as "job#employer_id",
+        job.start_date as "job#start_date",
+        job.end_date as "job#end_date",
         employer.id as "employer#id",
         employer.name as "employer#name"
       FROM person
@@ -325,7 +379,7 @@ Some things to note:
 
 ### Step 5: Writing the Controller Code
 
-We can now return to our controller code, and use our person data access function.
+We can now return to our controller code, and use our data access function.
 
 ```diff
 // app.ts
@@ -345,23 +399,23 @@ app.get('/rest/person', (req: Request, res: Response) => {
 -         id: 277,
 -         personId: 55,
 -         employerId: 17,
--         startDate: '2020-01-01',
--         endDate: '2020-12-31',
 -         employer: {
 -           id: 17,
 -           name: 'Good Corp'
--         }
+-         },
+-         startDate: '2020-01-01',
+-         endDate: '2020-12-31'
 -       },
 -       {
 -         id: 278,
 -         personId: 55,
 -         employerId: 26,
--         startDate: '2021-01-01',
--         endDate: '2021-12-31',
 -         employer: {
 -           id: 26,
 -           name: 'Better Corp'
--         }
+-         },
+-         startDate: '2021-01-01',
+-         endDate: '2021-12-31'
 -       }
 -     ]
 -   }