DB

Moduł DB zapewnia dostęp do bazy danych MongoDB zarządzanej przez platformę Orbito. Zamiast bezpośredniego klienta MongoDB, moduł korzysta z klasy Schema – uproszczonego ORM z walidacją danych i hookami cyklu życia.

const { DB } = require('@orbito/api-lib');

DB.Schema

DB.Schema definiuje strukturę kolekcji MongoDB wraz z typami pól, wartościami domyślnymi i walidacją. Instancja schematu jest jednocześnie interfejsem do wykonywania operacji na kolekcji.

Walidacja danych

Do walidacji pól schematu używana jest biblioteka fastest-validator. Definicje pól są zgodne z jej konwencją – każde pole jest domyślnie wymagane. Aby pole było opcjonalne, użyj flagi optional: true.

Brak kompatybilności z Mongoose

Choć API DB.Schema przypomina Mongoose, nie jest z nim kompatybilne. Metody takie jak find czy findOne zwracają tablice i obiekty POJO (zwykłe obiekty JavaScript), a nie instancje dokumentów Mongoose. Nie działają tu np. metody instancji, middleware per-dokument ani save().

new DB.Schema(collectionName, fieldDefinitions)

Parametr	Typ	Opis
`collectionName`	`string`	Logiczna nazwa kolekcji, np. `'orders'`
`fieldDefinitions`	`object`	Definicja pól kolekcji

Izolacja danych

Podajesz surową, logiczną nazwę kolekcji. Platforma sama nadaje jej namespace instalacji modułu, więc każda instancja ma własną, odizolowaną kolekcję – dwa sklepy obsługiwane przez ten sam moduł nie widzą nawzajem swoich danych. Nie prefiksuj nazw samodzielnie. Szczegóły w Kontekst firmy i instancji.

Dostępne typy pól

Typ	Opis
`string`	Tekst
`number`	Liczba
`boolean`	Wartość logiczna
`date`	Data
`ObjectId`	Identyfikator MongoDB
`array`	Tablica (z opcjonalnym `items`)
`object`	Zagnieżdżony obiekt

Przykład definicji schematu

const { DB } = require('@orbito/api-lib');

const OrdersSchema = new DB.Schema('orders', {
  orderNumber: { type: 'string' },
  cart:        { type: 'array',  items: { type: 'object' }, optional: true, default: [] },
  total:       { type: 'number', optional: true, default: 0 },
  createdAt:   { type: 'date',   optional: true, default: () => new Date() }
});

module.exports = OrdersSchema;

Nie dodawaj pola companyId

Schemat nie powinien zawierać pola companyId. Izolacja danych jest realizowana przez platformę na poziomie kolekcji, a nie przez pole dokumentu.

Automatyczna konwersja typów

Schema automatycznie rzutuje string w formacie 24-hex na ObjectId w zapytaniach find i findOne, jeśli pole ma typ ObjectId.

Operacje CRUD

Wszystkie operacje są asynchroniczne i wykonywane przez instancję schematu.

create

Tworzy nowy dokument z walidacją schematu.

const order = await OrdersSchema.create({
  orderNumber: 'ORD-001',
  cart: [
    { name: 'Produkt A', price: 49.99, quantity: 2 }
  ]
});
// order._id jest automatycznie przypisany przez MongoDB

find

Zwraca listę dokumentów spełniających kryteria.

const orders = await OrdersSchema.find(filter, limit?, skip?, sort?)

// Wszystkie zamówienia firmy, posortowane od najnowszych, max 50
const orders = await OrdersSchema.find(
  {},
  50,
  0,
  { createdAt: -1 }
);

findOne

Zwraca pierwszy dokument spełniający kryteria lub null.

const order = await OrdersSchema.findOne({ orderNumber: 'ORD-001' });

if (!order) {
  throw new Error('Zamówienie nie istnieje');
}

update

Aktualizuje dokumenty spełniające kryteria. Obsługuje operatory MongoDB ($set, $inc, $push itp.).

const result = await OrdersSchema.update(
  { _id: order._id },
  { $set: { total: 149.99 } }
);

delete

Usuwa dokumenty spełniające kryteria.

const deleted = await OrdersSchema.delete({ _id: order._id });

Hooki schematu

Hooki pozwalają reagować na zdarzenia cyklu życia dokumentu. Wykonują się automatycznie przed lub po danej operacji.

pre – przed operacją

OrdersSchema.pre('validate', function(data) {
  // Przelicz total przed walidacją i zapisem
  if (data.cart && Array.isArray(data.cart)) {
    data.total = data.cart.reduce(
      (sum, item) => sum + (item.price * item.quantity),
      0
    );
  }
});

post – po operacji

OrdersSchema.post('create', function(doc) {
  // Wywołaj log lub powiadomienie po utworzeniu dokumentu
  Log.info('Nowe zamówienie utworzone', { orderId: doc._id });
});

Hook	Kiedy wywoływany
`pre('validate', fn)`	Przed walidacją pól i zapisem (`create`)
`post('create', fn)`	Po pomyślnym utworzeniu dokumentu

Indeksy

Indeksy tworzysz przez DB.createIndex – metoda działa bezpośrednio na kolekcji MongoDB. Twórz indeksy przy starcie modułu, zanim zaczniesz wykonywać zapytania.

DB.createIndex(collectionName, fields, options?)

// Unikalny indeks – gwarancja braku duplikatów w obrębie firmy
DB.createIndex(
  'orders',
  { orderNumber: 1 },
  { unique: true }
);

// Indeks do szybkiego sortowania po dacie
DB.createIndex('orders', { createdAt: -1 });

Indeksy bez companyId

Każda instalacja modułu ma własną kolekcję, więc indeks obejmuje wyłącznie jej dokumenty – nie dodawaj companyId do definicji indeksu. Ograniczenie unique również działa automatycznie w obrębie jednej instalacji.