Relation Class Documentation

The Relation class provides a mechanism to handle relationships between collections in a database. It supports one-to-one, one-to-many, and many-to-many relationships.

Class: Relation

Constructor: Relation(dbs)

Creates a new instance of the Relation class.

• Parameters:
  • dbs (RelationTypes.DBS): An object mapping database names to DataBase or DataBaseRemote instances.

Method: async findOne(path, search, relations, select?)

Finds a single entry in a collection and resolves its relations.

• Parameters:

  • path (RelationTypes.Path): A tuple specifying the database and collection.
  • search (Search): The search criteria.
  • relations (RelationTypes.Relation): The relations to resolve.
  • select (RelationTypes.FieldPath[], optional): Fields to select in the result.

• Returns:

  • Promise<Object | null>: The found entry with resolved relations, or null if no match is found.

Method: async find(path, search, relations, select?, findOpts?)

Finds multiple entries in a collection and resolves their relations.

• Parameters:

  • path (RelationTypes.Path): A tuple specifying the database and collection.
  • search (Search): The search criteria.
  • relations (RelationTypes.Relation): The relations to resolve.
  • select (RelationTypes.FieldPath[], optional): Fields to select in the results.
  • findOpts (DbFindOpts, optional): Options for the find operation.

• Returns:

  • Promise<Object[]>: An array of found entries with resolved relations.

Relation Types

The Relation class supports the following relation types:

1. One-to-One ("1"): Resolves a single related entry.
2. One-to-Many ("1n"): Resolves multiple related entries.
3. Many-to-Many ("nm"): Resolves all entries in the related collection.

Example Usage

import Relation from "@wxn0brp/db";
import { autoCreate } from "@wxn0brp/db";

// Create database instances
const db1 = autoCreate("path/to/db1");
const db2 = autoCreate("path/to/db2");

// Define databases
const dbs = {
    db1,
    db2
};

// Define relations
const relations = {
    author: {
        path: ["db1", "users"],
        pk: "authorId",
        fk: "_id",
        type: "1",
        select: ["name", "email"]
    },
    comments: {
        path: ["db2", "comments"],
        pk: "_id",
        fk: "postId",
        type: "1n",
        select: ["content", "createdAt"]
    }
};

// Create a Relation instance
const relation = new Relation(dbs);

// Find a single post with relations
const post = await relation.findOne(
    ["db1", "posts"],
    { _id: "post123" },
    relations,
    [["title"], ["author.name"], ["comments.content"]]
);

console.log(post);

// Find multiple posts with relations
const posts = await relation.find(
    ["db1", "posts"],
    { category: "tech" },
    relations,
    [["title"], ["author.name"], ["comments.content"]],
    { max: 10 }
);

console.log(posts);

This example demonstrates how to use the Relation class to resolve relationships between collections in different databases.