orange-orm
Version:
Object Relational Mapper
1,483 lines (1,206 loc) • 74.7 kB
Markdown
<div align="center">
<img src="./docs/orange.svg" alt="Orange ORM Logo" width="250"/>
</div>
The ultimate Object Relational Mapper for Node.js, Bun and Deno, offering seamless integration with a variety of popular databases. Orange ORM supports both TypeScript and JavaScript, including both CommonJS and ECMAScript.
[](https://www.npmjs.org/package/orange-orm)
[](https://github.com/alfateam/orange-orm/actions)
[](https://github.com/alfateam/orange-orm/actions)
[](https://github.com/alfateam/orange-orm)
[](https://github.com/alfateam/orange-orm/discussions)
[](https://discord.gg/QjuEgvQXzd)
[](https://youtu.be/1IwwjPr2lMs)
## Key Features
- **Rich Querying Model**: Orange provides a powerful and intuitive querying model, making it easy to retrieve, filter, and manipulate data from your databases.
- **Active Record**: With a concise and expressive syntax, Orange enables you to interact with your database using the [*Active Record Pattern*](https://en.wikipedia.org/wiki/Active_record_pattern).
- **No Code Generation Required**: Enjoy full IntelliSense, even in table mappings, without the need for cumbersome code generation.
- **TypeScript and JavaScript Support**: Orange fully supports both TypeScript and JavaScript, allowing you to leverage the benefits of static typing and modern ECMAScript features.
- **Works in the Browser**: You can securely use Orange in the browser by utilizing the Express.js plugin, which serves to safeguard sensitive database credentials from exposure at the client level and protect against SQL injection. This method mirrors a traditional REST API, augmented with advanced TypeScript tooling for enhanced functionality.
## Supported Databases and Runtimes
| | Node | Deno | Bun |Cloudflare | Web |
| ------------- | :-----: | :-----: | :-----: | :-----: | :-----: |
| Postgres | ✅ | ✅ | ✅ | ✅|
| PGlite | ✅ | ✅ | ✅ | ✅ | ✅
| MS SQL | ✅ | | ✅ | |
| MySQL | ✅ | ✅ | ✅ ||
| Oracle | ✅ | ✅ | ✅ | |
| SAP ASE | ✅ | | | |
| SQLite | ✅ | ✅ | ✅ | |
| Cloudflare D1 | | | | ✅|
This is the _Modern Typescript Documentation_. Are you looking for the [_Classic Documentation_](https://github.com/alfateam/orange-orm/blob/master/docs/docs.md) ?
## Sponsorship <span style="font-size: larger; color: darkred;">♡</span>
If you value the hard work behind Orange and wish to see it evolve further, consider [sponsoring](https://github.com/sponsors/lroal). Your support fuels the journey of refining and expanding this tool for our developer community.
## Installation
```bash
npm install orange-orm
```
## Example
Watch the [tutorial video on YouTube](https://youtu.be/1IwwjPr2lMs)
<sub>📄 map.ts</sub>
```javascript
import orange from 'orange-orm';
const map = orange.map(x => ({
customer: x.table('customer').map(({ column }) => ({
id: column('id').numeric().primary().notNullExceptInsert(),
name: column('name').string(),
balance: column('balance').numeric(),
isActive: column('isActive').boolean(),
})),
order: x.table('_order').map(({ column }) => ({
id: column('id').numeric().primary().notNullExceptInsert(),
orderDate: column('orderDate').date().notNull(),
customerId: column('customerId').numeric().notNullExceptInsert(),
})),
orderLine: x.table('orderLine').map(({ column }) => ({
id: column('id').numeric().primary(),
orderId: column('orderId').numeric(),
product: column('product').string(),
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(),
name: column('name').string(),
street: column('street').string(),
postalCode: column('postalCode').string(),
postalPlace: column('postalPlace').string(),
countryCode: column('countryCode').string(),
}))
})).map(x => ({
orderLine: x.orderLine.map(({ hasMany }) => ({
packages: hasMany(x.package).by('lineId')
})),
order: x.order.map(v => ({
customer: v.references(x.customer).by('customerId'),
lines: v.hasMany(x.orderLine).by('orderId'),
deliveryAddress: v.hasOne(x.deliveryAddress).by('orderId'),
}))
}));
export default map;
```
<sub>📄 update.ts</sub>
```javascript
import map from './map';
const db = map.sqlite('demo.db');
updateRow();
async function updateRow() {
const order = await db.order.getById(2, {
lines: true
});
order.lines.push({
product: 'broomstick',
amount: 300
});
await order.saveChanges();
}
```
<sub>📄 filter.ts</sub>
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const orders = await db.order.getAll({
where: x => x.lines.any(line => line.product.contains('broomstick'))
.and(x.customer.name.startsWith('Harry')),
lines: {
packages: true
},
deliveryAddress: true,
customer: true
});
}
```
## API
<details id="table-mapping"><summary><strong>Mapping tables</strong></summary>
<p>To define a mapping, you employ the <strong><i>map()</i></strong> method, linking your tables and columns to corresponding object properties. You provide a callback function that engages with a parameter representing a database table.
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'. 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
import orange from 'orange-orm';
const map = orange.map(x => ({
customer: x.table('customer').map(({ column }) => ({
id: column('id').numeric().primary().notNullExceptInsert(),
name: column('name').string(),
balance: column('balance').numeric(),
isActive: column('isActive').boolean(),
})),
order: x.table('_order').map(({ column }) => ({
id: column('id').numeric().primary().notNullExceptInsert(),
orderDate: column('orderDate').date().notNull(),
customerId: column('customerId').numeric().notNullExceptInsert(),
})),
orderLine: x.table('orderLine').map(({ column }) => ({
id: column('id').numeric().primary(),
orderId: column('orderId').numeric(),
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(),
name: column('name').string(),
street: column('street').string(),
postalCode: column('postalCode').string(),
postalPlace: column('postalPlace').string(),
countryCode: column('countryCode').string(),
}))
})).map(x => ({
orderLine: x.orderLine.map(({ hasMany }) => ({
packages: hasMany(x.package).by('lineId')
})),
order: x.order.map(({ hasOne, hasMany, references }) => ({
customer: references(x.customer).by('customerId'),
deliveryAddress: hasOne(x.deliveryAddress).by('orderId'),
lines: hasMany(x.orderLine).by('orderId')
}))
}));
export default map;
```
The init.ts script resets our SQLite database. It's worth noting that SQLite databases are represented as single files, which makes them wonderfully straightforward to manage.
At the start of the script, we import our database mapping from the map.ts file. This gives us access to the db object, which we'll use to interact with our SQLite database.
Then, we define a SQL string. This string outlines the structure of our SQLite database. It first specifies to drop existing tables named 'deliveryAddress', 'package', 'orderLine', '_order', and 'customer' if they exist. This ensures we have a clean slate. Then, it dictates how to create these tables anew with the necessary columns and constraints.
Because of a peculiarity in SQLite, which only allows one statement execution at a time, we split this SQL string into separate statements. We do this using the split() method, which breaks up the string at every semicolon.
<sub>📄 init.ts</sub>
```javascript
import map from './map';
const db = map.sqlite('demo.db');
const sql = `DROP TABLE IF EXISTS deliveryAddress; DROP TABLE IF EXISTS package; DROP TABLE IF EXISTS orderLine; DROP TABLE IF EXISTS _order; DROP TABLE IF EXISTS customer;
CREATE TABLE customer (
id INTEGER PRIMARY KEY,
name TEXT,
balance NUMERIC,
isActive INTEGER
);
CREATE TABLE _order (
id INTEGER PRIMARY KEY,
orderDate TEXT,
customerId INTEGER REFERENCES customer
);
CREATE TABLE orderLine (
id INTEGER PRIMARY KEY,
orderId INTEGER REFERENCES _order,
product TEXT,
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,
name TEXT,
street TEXT,
postalCode TEXT,
postalPlace TEXT,
countryCode TEXT
)
`;
async function init() {
const statements = sql.split(';');
for (let i = 0; i < statements.length; i++) {
await db.query(statements[i]);
}
}
export default init;
```
In SQLite, columns with the INTEGER PRIMARY KEY attribute are designed to autoincrement by default. This means that each time a new record is inserted into the table, SQLite automatically produces a numeric key for the id column that is one greater than the largest existing key. This mechanism is particularly handy when you want to create unique identifiers for your table rows without manually entering each id.
</details>
<details><summary><strong>Connecting</strong></summary>
__SQLite__
When running **Node.js 21 and earlier**, you need to install the `sqlite3` dependency.
When running Node.js 22 and later, Bun, or Deno, you don't need it as it is built-in.
```bash
npm install sqlite3
```
```javascript
import map from './map';
const db = map.sqlite('demo.db');
// … use the database …
// IMPORTANT for serverless functions:
await db.close(); // closes the client connection
```
__With connection pool__
```bash
npm install sqlite3
```
```javascript
import map from './map';
const db = map.sqlite('demo.db', { size: 10 });
// … use the pool …
// IMPORTANT for serverless functions:
await pool.close(); // closes all pooled connections
```
__Why close ?__
In serverless environments (e.g. AWS Lambda, Vercel, Cloudflare Workers) execution contexts are frequently frozen and resumed. Explicitly closing the client or pool ensures that file handles are released promptly and prevents “database locked” errors between invocations.
__From the browser__
You can securely use Orange from the browser by utilizing the Express plugin, which serves to safeguard sensitive database credentials from exposure at the client level. This technique bypasses the need to transmit raw SQL queries directly from the client to the server. Instead, it logs method calls initiated by the client, which are later replayed and authenticated on the server. This not only reinforces security by preventing the disclosure of raw SQL queries on the client side but also facilitates a smoother operation. Essentially, this method mirrors a traditional REST API, augmented with advanced TypeScript tooling for enhanced functionality. You can read more about it in the section called [In the browser](#user-content-in-the-browser)
<sub>📄 server.ts</sub>
```javascript
import map from './map';
import { json } from 'body-parser';
import express from 'express';
import cors from 'cors';
const db = map.sqlite('demo.db');
express().disable('x-powered-by')
.use(json({ limit: '100mb' }))
.use(cors())
//for demonstrational purposes, authentication middleware is not shown here.
.use('/orange', db.express())
.listen(3000, () => console.log('Example app listening on port 3000!'));
```
<sub>📄 browser.ts</sub>
```javascript
import map from './map';
const db = map.http('http://localhost:3000/orange');
```
__MySQL__
```bash
$ npm install mysql2
```
```javascript
import map from './map';
const db = map.mysql('mysql://test:test@mysql/test');
```
__MS SQL__
```bash
npm install tedious
```
```javascript
import map from './map';
const db = map.mssql({
server: 'mssql',
options: {
encrypt: false,
database: 'test'
},
authentication: {
type: 'default',
options: {
userName: 'sa',
password: 'P@assword123',
}
}
});
```
__PostgreSQL__
With Bun, you don't need to install the `pg` package as PostgreSQL support is built-in.
```bash
npm install pg
```
```javascript
import map from './map';
const db = map.postgres('postgres://postgres:postgres@postgres/postgres');
```
With schema
```javascript
import map from './map';
const db = map.postgres('postgres://postgres:postgres@postgres/postgres?search_path=custom');
```
__PGlite__
```bash
npm install @electric-sql/pglite
```
In this example we use the in-memory Postgres.
Read more about [PGLite connection configs](https://pglite.dev/docs/).
```javascript
import map from './map';
const db = map.pglite( /* config? : PGliteOptions */);
```
__Cloudflare D1__
<sub>📄 wrangler.toml</sub>
```toml
name = "d1-tutorial"
main = "src/index.ts"
compatibility_date = "2025-02-04"
# Bind a D1 database. D1 is Cloudflare’s native serverless SQL database.
# Docs: https://developers.cloudflare.com/workers/wrangler/configuration/#d1-databases
[[d1_databases]]
binding = "DB"
database_name = "<your-name-for-the-database>"
database_id = "<your-guid-for-the-database>"
```
<sub>📄 src/index.ts</sub>
```javascript
import map from './map';
export interface Env {
// Must match the binding name in wrangler.toml
DB: D1Database;
}
export default {
async fetch(request, env): Promise<Response> {
const db = map.d1(env.DB);
const customers = await db.customer.getAll();
return Response.json(customers);
},
} satisfies ExportedHandler<Env>;
```
__Oracle__
```bash
npm install oracledb
```
```javascript
import map from './map';
const db = map.oracle({
user: 'sys',
password: 'P@assword123',
connectString: 'oracle/XE',
privilege: 2
});
```
__SAP Adaptive Server__
Even though msnodesqlv8 was developed for MS SQL, it also works for SAP ASE as it is ODBC compliant.
```bash
npm install msnodesqlv8
```
```javascript
import { fileURLToPath } from 'url';
import { dirname } from 'path';
import map from './map';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
//download odbc driver from sap web pages
const db = map.sap(`Driver=${__dirname}/libsybdrvodb.so;SERVER=sapase;Port=5000;UID=sa;PWD=sybase;DATABASE=test`);
```
</details>
<details id="inserting-rows"><summary><strong>Inserting rows</strong></summary>
<p>In the code below, we initially import the table-mapping feature "map.ts" and the setup script "init.ts", both of which were defined in the preceding step. The setup script executes a raw query that creates the necessary tables. Subsequently, we insert two customers, named "George" and "Harry", into the customer table, and this is achieved through calling "db.customer.insert".
Next, we insert an array of two orders in the order table. Each order contains an orderDate, customer information, deliveryAddress, and lines for the order items. We use the customer constants "george" and "harry" from previous inserts. Observe that we don't pass in any primary keys. This is because all tables here have autoincremental keys. The second argument to "db.order.insert" specifies a fetching strategy. This fetching strategy plays a critical role in determining the depth of the data retrieved from the database after insertion. The fetching strategy specifies which associated data should be retrieved and included in the resulting orders object. In this case, the fetching strategy instructs the database to retrieve the customer, deliveryAddress, and lines for each order.
Without a fetching strategy, "db.order.insert" would only return the root level of each order. In that case you would only get the id, orderDate, and customerId for each order.</p>
```javascript
import map from './map';
const db = map.sqlite('demo.db');
import init from './init';
insertRows();
async function insertRows() {
await init();
const george = await db.customer.insert({
name: 'George',
balance: 177,
isActive: true
});
const harry = await db.customer.insert({
name: 'Harry',
balance: 200,
isActive: true
});
const orders = await db.order.insert([
{
orderDate: new Date(2022, 0, 11, 9, 24, 47),
customer: george,
deliveryAddress: {
name: 'George',
street: 'Node street 1',
postalCode: '7059',
postalPlace: 'Jakobsli',
countryCode: 'NO'
},
lines: [
{ product: 'Bicycle', amount: 250 },
{ product: 'Small guitar', amount: 150 }
]
},
{
customer: harry,
orderDate: new Date(2021, 0, 11, 12, 22, 45),
deliveryAddress: {
name: 'Harry Potter',
street: '4 Privet Drive, Little Whinging',
postalCode: 'GU4',
postalPlace: 'Surrey',
countryCode: 'UK'
},
lines: [
{ product: 'Magic wand', amount: 300 }
]
}
], {customer: true, deliveryAddress: true, lines: true}); //fetching strategy
}
```
__Conflict resolution__
By default, the strategy for inserting rows is set to an optimistic approach. In this case, if a row is being inserted with an already existing primary key, the database raises an exception.
Currently, there are three concurrency strategies:
- <strong>`optimistic`</strong> Raises an exception if another row was already inserted on that primary key.
- <strong>`overwrite`</strong> Overwrites the property, regardless of changes by others.
- <strong>`skipOnConflict`</strong> Silently avoids updating the property if another user has modified it in the interim.
The <strong>concurrency</strong> option can be set either for the whole table or individually for each column. In the example below, we've set the concurrency strategy on <strong>vendor</strong> table to <strong>overwrite</strong> except for the column <strong>balance</strong> which uses the <strong>skipOnConflict</strong> strategy. In this particular case, a row with <strong>id: 1</strong> already exists, the <strong>name</strong> and <strong>isActive</strong> fields will be overwritten, but the balance will remain the same as in the original record, demonstrating the effectiveness of combining multiple <strong>concurrency</strong> strategies.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
insertRows();
async function insertRows() {
db2 = db({
vendor: {
balance: {
concurrency: 'skipOnConflict'
},
concurrency: 'overwrite'
}
});
await db2.vendor.insert({
id: 1,
name: 'John',
balance: 100,
isActive: true
});
//this will overwrite all fields but balance
const george = await db2.vendor.insert({
id: 1,
name: 'George',
balance: 177,
isActive: false
});
console.dir(george, {depth: Infinity});
// {
// id: 1,
// name: 'George',
// balance: 100,
// isActive: false
// }
}
```
</details>
<details><summary><strong>Fetching rows</strong></summary>
<p>Orange has a rich querying model. As you navigate through, you'll learn about the various methods available to retrieve data from your tables, whether you want to fetch all rows, many rows with specific criteria, or a single row based on a primary key.
The fetching strategy in Orange is optional, and its use is influenced by your specific needs. You can define the fetching strategy either on the table level or the column level. This granularity gives you the freedom to decide how much related data you want to pull along with your primary request.</p>
__All rows__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const orders = await db.order.getAll({
customer: true,
deliveryAddress: true,
lines: {
packages: true
}
});
}
```
__Limit, offset and order by__
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';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const orders = await db.order.getAll({
offset: 1,
orderBy: ['orderDate desc', 'id'],
limit: 10,
customer: true,
deliveryAddress: true,
lines: {
packages: true,
orderBy: 'product'
},
});
}
```
<a name="aggregate-results"> </a>
__With aggregated results__
You can count records and aggregate numerical columns.
The following operators are supported:
- count
- sum
- min
- max
- avg
You can also elevate associated data to a parent level for easier access. In the example below, <i>balance</i> of the customer is elevated to the root level.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const orders = await db.order.getAll({
numberOfLines: x => x.count(x => x.lines.id),
totalAmount: x => x.sum(x => lines.amount),
balance: x => x.customer.balance
});
}
```
__Many rows filtered__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const orders = await db.order.getAll({
where: x => x.lines.any(line => line.product.contains('i'))
.and(x.customer.balance.greaterThan(180)),
customer: true,
deliveryAddress: true,
lines: true
});
}
```
You can also use the alternative syntax for the `where-filter`. This way, the filter can be constructed independently from the fetching strategy. Keep in mind that you must use the `getMany` method instead of the `getAll` method.
It is also possible to combine `where-filter` with the independent filter when using the `getMany` method.
```javascript
async function getRows() {
const filter = db.order.lines.any(line => line.product.contains('i'))
.and(db.order.customer.balance.greaterThan(180));
const orders = await db.order.getMany(filter, {
//where: x => ... can be combined as well
customer: true,
deliveryAddress: true,
lines: true
});
}
```
__Single row filtered__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const order = await db.order.getOne(undefined /* optional filter */, {
where: x => x.customer(customer => customer.isActive.eq(true)
.and(customer.startsWith('Harr'))),
customer: true,
deliveryAddress: true,
lines: true
});
}
```
You can use also the alternative syntax for the `where-filter`. This way, the filter can be constructed independently from the fetching strategy.
It is also possible to combine `where-filter` with the independent filter when using the `getOne` method.
```javascript
async function getRows() {
const filter = db.order.customer(customer => customer.isActive.eq(true)
.and(customer.startsWith('Harr')));
//equivalent, but creates slighly different sql:
// const filter = db.order.customer.isActive.eq(true).and(db.order.customer.startsWith('Harr'));
const order = await db.order.getOne(filter, {
customer: true,
deliveryAddress: true,
lines: true
});
}
```
__Single row by primary key__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const order = await db.order.getById(1, {
customer: true,
deliveryAddress: true,
lines: true
});
}
```
__Many rows by primary key__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const orders = await db.order.getMany([
{id: 1},
{id: 2}
],
{
customer: true,
deliveryAddress: true,
lines: true
});
}
```
</details>
<details id="updating-rows"><summary><strong>Updating rows</strong></summary>
<p>To update rows, modify the property values and invoke the method <strong><i>saveChanges()</i></strong>. The function updates only the modified columns, not the entire row. Rows in child relations can also be updated as long as the parent order <i>owns</i> the child tables. In our illustration, the <strong>order</strong> table owns both the <strong>deliveryAddress</strong> and the <strong>lines</strong> tables because they're part of a <i>hasOne/hasMany relationship</i>. Contrastingly, the <strong>customer</strong> is part of a <i>reference relationship</i> and thus can't be updated here. But you can detach the reference to the customer by assigning it to null or undefined. (Setting order.customerId to null or undefined achieves the same result.)</p>
__Updating a single row__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
update();
async function update() {
const order = await db.order.getById(1, {
customer: true,
deliveryAddress: true,
lines: true
});
order.orderDate = new Date();
order.deliveryAddress = null;
order.lines.push({product: 'Cloak of invisibility', amount: 600});
await order.saveChanges();
}
```
__Updating many rows__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
update();
async function update() {
let orders = await db.order.getAll({
orderBy: 'id',
lines: true,
deliveryAddress: true,
customer: true
});
orders[0].orderDate = new Date();
orders[0].deliveryAddress.street = 'Node street 2';
orders[0].lines[1].product = 'Big guitar';
orders[1].orderDate = '2023-07-14T12:00:00'; //iso-string is allowed
orders[1].deliveryAddress = null;
orders[1].customer = null;
orders[1].lines.push({product: 'Cloak of invisibility', amount: 600});
await orders.saveChanges();
}
```
__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';
const db = map.sqlite('demo.db');
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
},
deliveryAddress: {
name: 'Roger', //modified name
street: 'Node street 1',
postalCode: '7059',
postalPlace: 'Jakobsli',
countryCode: 'NO'
},
lines: [
{ id: 1, product: 'Bicycle', amount: 250 },
{ id: 2, product: 'Small guitar', amount: 150 },
{ product: 'Piano', amount: 800 } //the new line to be inserted
]
};
const order = await db.order.replace(modified, {customer: true, deliveryAddress: true, lines: true});
}
```
__Partially updating from JSON__
The updateChanges method applies a partial update based on difference between original and modified row. It is often preferable because it minimizes the risk of unintentionally overwriting data that may have been altered by other users in the meantime. To do so, you need to pass in the original row object before modification as well.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
update();
async function update() {
const original = {
id: 1,
orderDate: '2023-07-14T12:00:00',
customer: {
id: 2
},
deliveryAddress: {
id: 1,
name: 'George',
street: 'Node street 1',
postalCode: '7059',
postalPlace: 'Jakobsli',
countryCode: 'NO'
},
lines: [
{ id: 1, product: 'Bicycle', amount: 250 },
{ id: 2, product: 'Small guitar', amount: 150 }
]
};
const modified = JSON.parse(JSON.stringify(original));
modified.deliveryAddress.name = 'Roger';
modified.lines.push({ product: 'Piano', amount: 800 });
const order = await db.order.updateChanges(modified, original, { customer: true, deliveryAddress: true, lines: true });
}
```
__Conflict resolution__
Rows get updated using an <i id="conflicts">optimistic</i> concurrency approach by default. This means if a property being edited was meanwhile altered, an exception is raised, indicating the row was modified by a different user. You can change the concurrency strategy either at the table or column level.
Currently, there are three concurrency strategies:
- <strong>`optimistic`</strong> Raises an exception if another user changes the property during an update.
- <strong>`overwrite`</strong> Overwrites the property, regardless of changes by others.
- <strong>`skipOnConflict`</strong> Silently avoids updating the property if another user has modified it in the interim.
In the example below, we've set the concurrency strategy for orderDate to 'overwrite'. This implies that if other users modify orderDate while you're making changes, their updates will be overwritten.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
update();
async function update() {
const order = await db.order.getById(1, {
customer: true,
deliveryAddress: true,
lines: true
});
order.orderDate = new Date();
order.deliveryAddress = null;
order.lines.push({product: 'Cloak of invisibility', amount: 600});
await order.saveChanges( {
orderDate: {
concurrency: 'overwrite'
}});
}
```
</details>
<details><summary><strong>Upserting rows</strong></summary>
It is possible to perform 'upserts' by taking advantage of the 'overwrite' strategy.
Currently, there are three concurrency strategies:
- <strong>`optimistic`</strong> Raises an exception if another row was already inserted on that primary key.
- <strong>`overwrite`</strong> Overwrites the property, regardless of changes by others.
- <strong>`skipOnConflict`</strong> Silently avoids updating the property if another user has modified it in the interim.
The <strong>concurrency</strong> option can be set either for the whole table or individually for each column. In the example below, we've set the concurrency strategy on <strong>vendor</strong> table to <strong>overwrite</strong> except for the column <strong>balance</strong> which uses the <strong>skipOnConflict</strong> strategy. In this particular case, a row with <strong>id: 1</strong> already exists, the <strong>name</strong> and <strong>isActive</strong> fields will be overwritten, but the balance will remain the same as in the original record, demonstrating the effectiveness of combining multiple <strong>concurrency</strong> strategies.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
insertRows();
async function insertRows() {
db2 = db({
vendor: {
balance: {
concurrency: 'skipOnConflict'
},
concurrency: 'overwrite'
}
});
await db2.vendor.insert({
id: 1,
name: 'John',
balance: 100,
isActive: true
});
//this will overwrite all fields but balance
const george = await db2.vendor.insert({
id: 1,
name: 'George',
balance: 177,
isActive: false
});
console.dir(george, {depth: Infinity});
// {
// id: 1,
// name: 'George',
// balance: 100,
// isActive: false
// }
}
```
</details>
<details><summary><strong>Deleting rows</strong></summary>
<p>Rows in owner tables cascade deletes to their child tables. In essence, if a table has ownership over other tables through <strong><i>hasOne</i></strong> and <strong><i>hasMany</i></strong> relationships, removing a record from the parent table also removes its corresponding records in its child tables. This approach safeguards against leaving orphaned records and upholds data integrity. On the contrary, tables that are merely referenced, through <strong><i>reference relationships </i></strong> , remain unaffected upon deletions. For a deeper dive into these relationships and behaviors, refer to the section on <a href="#user-content-table-mapping">Mapping tables</a>.</p>
__Deleting a single row__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
deleteRow();
async function deleteRow() {
const order = await db.order.getById(1);
await order.delete();
//will also delete deliveryAddress and lines
//but not customer
}
```
__Deleting a row in an array__
A common workflow involves retrieving multiple rows, followed by the need to delete a specific row from an array. This operation is straightforward to do with Orange, which allow for the updating, inserting, and deleting of multiple rows in a single transaction. To modify the array, simply add, update, or remove elements, and then invoke the saveChanges() method on the array to persist the changes.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
updateInsertDelete();
async function updateInsertDelete() {
const orders = await db.order.getAll({
customer: true,
deliveryAddress: true,
lines: true
});
//will add line to the first order
orders[0].lines.push({
product: 'secret weapon',
amount: 355
});
//will delete second row
orders.splice(1, 1);
//will insert a new order with lines, deliveryAddress and set customerId
orders.push({
orderDate: new Date(2022, 0, 11, 9, 24, 47),
customer: {
id: 1
},
deliveryAddress: {
name: 'George',
street: 'Node street 1',
postalCode: '7059',
postalPlace: 'Jakobsli',
countryCode: 'NO'
},
lines: [
{ product: 'Magic tent', amount: 349 }
]
});
await orders.saveChanges();
}
```
__Deleting many rows__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
deleteRows();
async function deleteRows() {
let orders = await db.order.getAll({
where: x => x.customer.name.eq('George')
});
await orders.delete();
}
```
__Deleting with concurrency__
Concurrent operations can lead to conflicts. When you still want to proceed with the deletion regardless of potential interim changes, the 'overwrite' concurrency strategy can be used. This example demonstrates deleting rows even if the "delivery address" has been modified in the meantime. You can read more about concurrency strategies in <a href="#user-content-updating-rows">Updating rows</a>.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
deleteRows();
async function deleteRows() {
let orders = await db.order.getAll({
where: x => x.deliveryAddress.name.eq('George'),
customer: true,
deliveryAddress: true,
lines: true
});
await orders.delete({
deliveryAddress: {
concurrency: 'overwrite'
}
});
}
```
__Batch delete__
When removing a large number of records based on a certain condition, batch deletion can be efficient.
However, it's worth noting that batch deletes don't follow the cascade delete behavior by default. To achieve cascading in batch deletes, you must explicitly call the deleteCascade method.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
deleteRows();
async function deleteRows() {
const filter = db.order.deliveryAddress.name.eq('George');
await db.order.delete(filter);
}
```
__Batch delete cascade__
When deleting records, sometimes associated data in related tables also needs to be removed. This cascade delete helps maintain database integrity.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
deleteRows();
async function deleteRows() {
const filter = db.order.deliveryAddress.name.eq('George');
await db.order.deleteCascade(filter);
}
```
__Batch delete by primary key__
For efficiency, you can also delete records directly if you know their primary keys.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
deleteRows();
async function deleteRows() {
db.customer.delete([{id: 1}, {id: 2}]);
}
```
</details>
<details id="in-the-browser"><summary><strong>In the browser</strong></summary>
<p>You can use <strong><i>Orange</i></strong> in the browser by using the adapter for Express. Instead of sending raw SQL queries from the client to the server, this approach records the method calls in the client. These method calls are then replayed at the server, ensuring a higher level of security by not exposing raw SQL on the client side.
Raw sql queries, raw sql filters and transactions are disabled at the http client due to security reasons. If you would like Orange to support other web frameworks, like nestJs, fastify, etc, please let me know.</p>
<sub>📄 server.ts</sub>
```javascript
import map from './map';
import { json } from 'body-parser';
import express from 'express';
import cors from 'cors';
const db = map.sqlite('demo.db');
express().disable('x-powered-by')
.use(json({ limit: '100mb' }))
.use(cors())
//for demonstrational purposes, authentication middleware is not shown here.
.use('/orange', db.express())
.listen(3000, () => console.log('Example app listening on port 3000!'));
```
<sub>📄 browser.ts</sub>
```javascript
import map from './map';
const db = map.http('http://localhost:3000/orange');
updateRows();
async function updateRows() {
const order = await db.order.getOne(undefined, {
where: x => x.lines.any(line => line.product.startsWith('Magic wand'))
.and(x.customer.name.startsWith('Harry'),
lines: true
});
order.lines.push({
product: 'broomstick',
amount: 300,
});
await order.saveChanges();
}
```
__Interceptors and base filter__
In the next setup, axios interceptors are employed on the client side to add an Authorization header of requests. Meanwhile, on the server side, an Express middleware (validateToken) is utilized to ensure the presence of the Authorization header, while a base filter is applied on the order table to filter incoming requests based on the customerId extracted from this header. This combined approach enhances security by ensuring that users can only access data relevant to their authorization level and that every request is accompanied by a token. In real-world applications, it's advisable to use a more comprehensive token system and expand error handling to manage a wider range of potential issues.
One notable side effect compared to the previous example, is that only the order table is exposed for interaction, while all other potential tables in the database remain shielded from direct client access (except for related tables). If you want to expose a table without a baseFilter, just set the tableName to an empty object.
<sub>📄 server.ts</sub>
```javascript
import map from './map';
import { json } from 'body-parser';
import express from 'express';
import cors from 'cors';
const db = map.sqlite('demo.db');
express().disable('x-powered-by')
.use(json({ limit: '100mb' }))
.use(cors())
.use('/orange', validateToken)
.use('/orange', db.express({
order: {
baseFilter: (db, req, _res) => {
const customerId = Number.parseInt(req.headers.authorization.split(' ')[1]); //Bearer 2
return db.order.customerId.eq(Number.parseInt(customerId));
}
}
}))
.listen(3000, () => console.log('Example app listening on port 3000!'));
function validateToken(req, res, next) {
// For demo purposes, we're just checking against existence of authorization header
// In a real-world scenario, this would be a dangerous approach because it bypasses signature validation
const authHeader = req.headers.authorization;
if (authHeader)
return next();
else
return res.status(401).json({ error: 'Authorization header missing' });
}
```
<sub>📄 browser.ts</sub>
```javascript
import map from './map';
const db = map.http('http://localhost:3000/orange');
updateRows();
async function updateRows() {
db.interceptors.request.use((config) => {
// For demo purposes, we're just adding hardcoded token
// In a real-world scenario, use a proper JSON web token
config.headers.Authorization = 'Bearer 2' //customerId
return config;
});
db.interceptors.response.use(
response => response,
(error) => {
if (error.response && error.response.status === 401) {
console.dir('Unauthorized, dispatch a login action');
//redirectToLogin();
}
return Promise.reject(error);
}
);
const order = await db.order.getOne(undefined, {
where: x => x.lines.any(line => line.product.startsWith('Magic wand'))
.and(db.order.customer.name.startsWith('Harry')),
lines: true
});
order.lines.push({
product: 'broomstick',
amount: 300
});
await order.saveChanges();
}
```
</details>
<details id="fetching-strategies"><summary><strong>Fetching strategies</strong></summary>
<p>Efficient data retrieval is crucial for the performance and scalability of applications. The fetching strategy gives you the freedom to decide how much related data you want to pull along with your primary request. Below are examples of common fetching strategies, including fetching entire relations and subsets of columns. When no fetching strategy is present, it will fetch all columns without its relations.<p>
__Including a relation__
This example fetches orders and their corresponding delivery addresses, including all columns from both entities.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.order.getAll({
deliveryAddress: true
});
}
```
__Including a subset of columns__
In scenarios where only specific fields are required, you can specify a subset of columns to include. In the example below, orderDate is explicitly excluded, so all other columns in the order table are included by default. For the deliveryAddress relation, only countryCode and name are included, excluding all other columns. If you have a mix of explicitly included and excluded columns, all other columns will be excluded from that table.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.order.getAll({
orderDate: false,
deliveryAddress: {
countryCode: true,
name: true
}
});
}
```
</details>
<details id="basic-filters"><summary><strong>Basic filters</strong></summary>
<p>Filters are a versatile tool for both data retrieval and bulk deletions. They allow for precise targeting of records based on specific criteria and can be combined with operators like <i>any</i> and <i>exists</i> and even raw sql for more nuanced control. Filters can also be nested to any depth, enabling complex queries that can efficiently manage and manipulate large datasets. This dual functionality enhances database management by ensuring data relevance and optimizing performance.</p>
__Equal__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.customer.getAll({
where x => x.name.equal('Harry')
});
}
```
__Not equal__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.customer.getAll({
where x => x.name.notEqual('Harry')
});
}
```
__Contains__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.customer.getAll({
where: x => x.name.contains('arr')
});
}
```
__Starts with__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const filter = db.customer.name.startsWith('Harr');
const rows = await db.customer.getAll({
where: x => x.name.startsWith('Harr')
});
}
```
__Ends with__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.customer.getAll({
where: x => x.name.endsWith('arry')
});
}
```
__Greater than__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.order.getAll({
where: x => x.orderDate.greaterThan('2023-07-14T12:00:00')
});
}
```
__Greater than or equal__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.order.getAll({
where: x => x.orderDate.greaterThanOrEqual('2023-07-14T12:00:00')
});
}
```
__Less than__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.order.getAll({
where: x => x.orderDate.lessThan('2023-07-14T12:00:00')
});
}
```
__Less than or equal__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.order.getAll({
where: x => x.orderDate.lessThanOrEqual('2023-07-14T12:00:00')
});
}
```
__Between__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.order.getAll({
where: x => x.orderDate.between('2023-07-14T12:00:00', '2024-07-14T12:00:00')
});
}
```
__In__
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rows = await db.order.getAll({
where: x => x.customer.name.in('George', 'Harry')
});
}
```
__Raw sql filter__
You can use the raw SQL filter alone or in combination with a regular filter.
Here the raw filter queries for customer with name ending with "arry". The composite filter combines the raw SQL filter and a regular filter that checks for a customer balance greater than 100. It is important to note that due to security precautions aimed at preventing SQL injection attacks, using raw SQL filters directly via browser inputs is not allowed. Attempting to do so will result in an HTTP status 403 (Forbidden) being returned.
```javascript
import map from './map';
const db = map.sqlite('demo.db');
getRows();
async function getRows() {
const rawFilter = {
sql: 'name like ?',
parameters: ['%arry']
};
const rowsWithRaw = await db.customer.getAll({