orange-orm 3.10.2 → 4.0.0

package/README.md

@@ -4,7 +4,7 @@
 
 The ultimate Object Relational Mapper for Node.js and Typescript, offering seamless integration with a variety of popular databases. Whether you're building applications in TypeScript or JavaScript  (including both CommonJS and ECMAScript), Orange ORM has got you covered.  
 
-[![npm version](https://img.shields.io/npm/v/rdb.svg?style=flat-square)](https://www.npmjs.org/package/orange-orm)
+[![npm version](https://img.shields.io/npm/v/orange-orm.svg?style=flat-square)](https://www.npmjs.org/package/orange-orm)
 [![Build status](https://github.com/alfateam/orange-orm/workflows/Node.js%20CI/badge.svg)](https://github.com/alfateam/orange-orm/actions)
 [![Coverage Badge](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/lroal/1a69422f03da7f8155cf94fe66022452/raw/rdb__heads_master.json)](https://github.com/alfateam/orange-orm/actions)
 [![Github](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/lroal/1ccb2b79abbe0258d636e9b5e4630a1a/raw/rdb__heads_master.json)](https://github.com/alfateam/orange-orm)
@@ -46,7 +46,7 @@ $ npm install orange-orm
 ## Example
 Watch the [tutorial video on YouTube](https://youtu.be/1IwwjPr2lMs)
 
-![Relations diagram](./docs/relations.png)  
+![Relations diagram](./docs/diagram.svg)  
 
 Here we choose SQLite.  
 ```bash
@@ -77,6 +77,12 @@ const map = orange.map(x => ({
     amount: column('amount').numeric(),
   })),
 
+  package: x.table('package').map(({ column }) => ({
+    id: column('packageId').numeric().primary().notNullExceptInsert(),
+    lineId: column('lineId').numeric().notNullExceptInsert(),
+    sscc: column('sscc').string() //the barcode
+  })),
+
   deliveryAddress: x.table('deliveryAddress').map(({ column }) => ({
     id: column('id').numeric().primary(),
     orderId: column('orderId').numeric(),
@@ -87,6 +93,10 @@ const map = orange.map(x => ({
     countryCode: column('countryCode').string(),
   }))
 
+})).map(x => ({
+  orderLine: x.orderLine.map(({ hasMany }) => ({
+    packages: hasMany(x.package).by('lineId')
+  }))
 })).map(x => ({
   order: x.order.map(v => ({
     customer: v.references(x.customer).by('customerId'),
@@ -130,8 +140,10 @@ async function getRows() {
   const orders = await db.order.getAll({
     where: x => x.lines.any(line => line.product.contains('broomstick'))
       .and(db.order.customer.name.startsWith('Harry')),
-    lines: true,
-    deliveryAddress: true,
+    lines: {
+      packages: true
+    },
+    deliveryAddress: true,    
     customer: true
   });  
 }
@@ -145,7 +157,7 @@ async function getRows() {
 
 Each column within your database table is designated by using the <strong><i>column()</i></strong> method, in which you specify its name. This action generates a reference to a column object that enables you to articulate further column properties like its data type or if it serves as a primary key.
 
-Relationships between tables can also be outlined. By using methods like <strong><i>hasOne</i></strong>, <strong><i>hasMany</i></strong>, and <strong><i>references</i></strong>, you can establish connections that reflect the relationships in your data schema. In the example below, an 'order' is linked to a 'customer' reference, a 'deliveryAddress', and multiple 'lines'. The hasMany and hasOne relations represents ownership - the tables 'deliveryAddress' and 'orderLine' are owned by the 'order' table, and therefore, they contain the 'orderId' column referring to their parent table, which is 'order'. Conversely, the customer table is independent and can exist without any knowledge of the 'order' table. Therefore we say that the order table <i>references</i> the customer table - necessitating the existence of a 'customerId' column in the 'order' table.</p>
+Relationships between tables can also be outlined. By using methods like <strong><i>hasOne</i></strong>, <strong><i>hasMany</i></strong>, and <strong><i>references</i></strong>, you can establish connections that reflect the relationships in your data schema. In the example below, an 'order' is linked to a 'customer' reference, a 'deliveryAddress', and multiple 'lines'. The hasMany and hasOne relations represents ownership - the tables 'deliveryAddress' and 'orderLine' are owned by the 'order' table, and therefore, they contain the 'orderId' column referring to their parent table, which is 'order'. The similar relationship exists between orderLine and package - hence the packages are owned by the orderLine. Conversely, the customer table is independent and can exist without any knowledge of the 'order' table. Therefore we say that the order table <i>references</i> the customer table - necessitating the existence of a 'customerId' column in the 'order' table.</p>
 
 <sub>📄 map.ts</sub>
 ```javascript
@@ -171,6 +183,12 @@ const map = orange.map(x => ({
     product: column('product').string(),
   })),
 
+  package: x.table('package').map(({ column }) => ({
+    id: column('packageId').numeric().primary().notNullExceptInsert(),
+    lineId: column('lineId').numeric().notNullExceptInsert(),
+    sscc: column('sscc').string() //the barcode
+  })),
+
   deliveryAddress: x.table('deliveryAddress').map(({ column }) => ({
     id: column('id').numeric().primary(),
     orderId: column('orderId').numeric(),
@@ -181,6 +199,10 @@ const map = orange.map(x => ({
     countryCode: column('countryCode').string(),
   }))
 
+})).map(x => ({
+  orderLine: x.orderLine.map(({ hasMany }) => ({
+    packages: hasMany(x.package).by('lineId')
+  }))
 })).map(x => ({
   order: x.order.map(({ hasOne, hasMany, references }) => ({
     customer: references(x.customer).by('customerId'),
@@ -225,6 +247,12 @@ CREATE TABLE orderLine (
     amount NUMERIC(10,2)
 );
 
+CREATE TABLE package (
+    packageId INTEGER PRIMARY KEY,
+    lineId INTEGER REFERENCES orderLine,
+    sscc TEXT
+);
+
 CREATE TABLE deliveryAddress (
     id INTEGER PRIMARY KEY,
     orderId INTEGER REFERENCES _order,
@@ -329,7 +357,7 @@ $ npm install pg
 ```  
 ```javascript
 import map from './map';
-const db = map.pg('postgres://postgres:postgres@postgres/postgres');
+const db = map.postgres('postgres://postgres:postgres@postgres/postgres');
 ```
 __Oracle__
 ```bash
@@ -497,12 +525,14 @@ async function getRows() {
   const orders = await db.order.getAll({
     customer: true, 
     deliveryAddress: true, 
-    lines: true
+    lines: {
+      packages: true
+    }
   });
 }
 ```
 __Limit, offset and order by__  
-This script demonstrates how to fetch orders with customer, lines and deliveryAddress, limiting the results to 10, skipping the first row, and sorting the data based on the orderDate in descending order followed by id. The lines are sorted by product.  
+This script demonstrates how to fetch orders with customer, lines, packages and deliveryAddress, limiting the results to 10, skipping the first row, and sorting the data based on the orderDate in descending order followed by id. The lines are sorted by product.  
 
 ```javascript
 import map from './map';
@@ -518,6 +548,7 @@ async function getRows() {
     customer: true, 
     deliveryAddress: true, 
     lines: {
+      packages: true,
       orderBy: 'product'
     },
   });
@@ -593,7 +624,7 @@ getRows();
 
 async function getRows() {
   const order = await db.order.getOne(undefined /* optional filter */, {
-    where: x => x.order.customer(customer => customer.isActive.eq(true)
+    where: x => x.customer(customer => customer.isActive.eq(true)
                  .and(customer.startsWith('Harr'))),
     customer: true, 
     deliveryAddress: true, 
@@ -616,7 +647,6 @@ async function getRows() {
   });
 }
 ```
-```
 
 __Single row by primary key__
 
@@ -710,8 +740,8 @@ async function update() {
   await orders.saveChanges();
 }
 ```
-__Updating from JSON__  
-The update method is suitable when a complete overwrite is required from a JSON object - typically in a REST API. However, it's important to consider that this method replaces the entire row and it's children, which might not always be desirable in a multi-user environment.
+__Selective updates__  
+The update method is ideal for updating specific columns and relationships across one or multiple rows. You must provide a where filter to specify which rows to target. If you include a fetching strategy, the affected rows and their related data will be returned; otherwise, no data is returned.
 
 ```javascript
 import map from './map';
@@ -721,7 +751,33 @@ update();
 
 async function update() {
 
+  const propsToBeModified = {
+    orderDate: new Date(),
+    customerId: 2,
+    lines: [
+      { id: 1, product: 'Bicycle', amount: 250 }, //already existing line
+      { id: 2, product: 'Small guitar', amount: 150 }, //already existing line
+      { product: 'Piano', amount: 800 } //the new line to be inserted
+    ]
+  };
+
+  const strategy = {customer: true, deliveryAddress: true, lines: true};
+  const orders = await db.order.update(propsToBeModified, { where: x => x.id.eq(1) }, strategy);
+}
+```
+__Replacing a row from JSON__  
+The replace method is suitable when a complete overwrite is required from a JSON object - typically in a REST API. However, it's important to consider that this method replaces the entire row and it's children, which might not always be desirable in a multi-user environment.
+
+```javascript
+import map from './map';
+const db = map.sqlite('demo.db');
+
+replace();
+
+async function replace() {
+
   const modified = {
+    id: 1,
     orderDate: '2023-07-14T12:00:00',
     customer: {
       id: 2
@@ -740,7 +796,7 @@ async function update() {
     ]
   };
 
-  const order = await db.order.update(modified, {customer: true, deliveryAddress: true, lines: true});
+  const order = await db.order.replace(modified, {customer: true, deliveryAddress: true, lines: true});
 }
 ```
 __Partially updating from JSON__  
@@ -1795,7 +1851,7 @@ async function getRows() {
 ```
 </details>
 
-<details><summary><strong>Aggregate functions</strong></summary>
+<details id="aggregates"><summary><strong>Aggregate functions</strong></summary>
 
 You can count records and aggregate numerical columns.  This can either be done across rows or separately for each row.  
 Supported functions include:

package/docs/changelog.md

@@ -1,11 +1,15 @@
 ## Changelog
-__3.10.2_  
+__4.0.0__  
+Changed the behaviour of `update` to accept a `where` filter and only update passed in columns and relations. The previous behaviour of `update` has moved to `replace` method.  
+__3.10.3__  
+Fix duplicate method signatures for those still using code generation  
+__3.10.2__  
 Orange ORM was renamed from rdb. New installation url: [npmjs.org/package/orange-orm](https://npmjs.org/package/orange-orm) . Old url was npmjs.org/package/rdb  
-__3.10.1_  
+__3.10.1__  
 Bugfix: Adding hasOne row to existing parent throws.  See [#86](https://github.com/alfateam/orange-orm/issues/86)  
-__3.10.0_  
+__3.10.0__  
 Aggregate functions  
-__3.9.1_  
+__3.9.1__  
 Bugfix: Crashing on many relations if foreign key column is omitted in strategy.  See [#83](https://github.com/alfateam/orange-orm/issues/83)  
 __3.9.0__  
 Possible to elevate associated column on a related table to a parent table when fetching.  See https://github.com/alfateam/orange-orm/#user-content-aggregate-results