v1.1.0 Release Notes

This document outlines the latest additions to ts-orm for improved querying and relational data handling.

---

readOne

Fetch a single record that matches the given conditions.

Usage

const result = await readOne('users', { id: 'abc-123' });

if (result.success) {
  console.log('User:', result.data);
} else {
  console.log('Not found:', result.message);
}

Behavior

• Returns { success: true, data: {...} } if found
• Returns { success: false, data: null } if not found

---

findOrFail

Fetch a record by key or throw an error if it doesn't exist.

Usage

try {
  const user = await findOrFail('users', 'id', 'abc-123');
  console.log('User:', user);
} catch (err) {
  console.error(err.message); // Record not found in table 'users' with id = abc-123
}

Behavior

• Returns the record directly if found
• Throws Error if not found

---

readWith

Perform a SELECT query with JOINs based on JSON-configured relationships.

Syntax

readWith(table, conditions = {}, joins = [])

Usage

const result = await readWith('orders', { user_id: 42 }, [
  { table: 'users', on: ['orders.user_id', 'users.id'], type: 'inner' }
]);

if (result.success) {
  console.log(result.data);
}

Join Options

• type (optional): 'inner' (default), 'left', 'right'
• table: the table to join
• on: an array of two column paths: [leftColumn, rightColumn]

Example

[
  { table: 'users', on: ['orders.user_id', 'users.id'], type: 'left' },
  { table: 'products', on: ['orders.product_id', 'products.id'], type: 'right' }
]

Behavior

• Builds a raw SQL query with joins
• Returns all joined results in result.data

---

Example Scenario with readWith

Two tables:

CREATE TABLE orders (
  id VARCHAR(36) PRIMARY KEY,
  user_id VARCHAR(36),
  product_id VARCHAR(36)
);

CREATE TABLE users (
  id VARCHAR(36) PRIMARY KEY,
  name VARCHAR(128)
);

const result = await readWith('orders', { user_id: 'abc-123' }, [
  { table: 'users', on: ['orders.user_id', 'users.id'], type: 'inner' }
]);

This performs:

SELECT * FROM orders
JOIN users ON orders.user_id = users.id
WHERE orders.user_id = 'abc-123'