Relations & Field Types
Work with relations, atomic operations, files, galleries, and select fields in the Nimbu JS SDK.
The SDK decodes Nimbu field types into helper objects. These helpers know how to serialize changes back to the API.
Relations
Use relation(fieldName) for multi-reference fields.
const article = await new Nimbu.Query('articles').get(articleId);
const author = new Nimbu.Object('customers', { id: customerId });
article.relation('authors').add(author);
await article.save();Remove a relation:
article.relation('authors').remove(author);
await article.save();Read loaded relation values:
const authors = article.relation('authors').list();If you need relation values, include the relation when fetching the parent:
await article.fetchWithInclude('authors');
const authors = article.relation('authors').list();Atomic Operations
Atomic operations let the server apply field changes without overwriting the whole field.
article.increment('views', 1);
article.set('tags', new Nimbu.Atomic.AddUnique(['featured']));
article.set('old_tags', new Nimbu.Atomic.Remove(['draft']));
await article.save();Common operations:
| Operation | Use |
|---|---|
Nimbu.Atomic.Set(value) | Set a field. |
Nimbu.Atomic.Unset() | Remove a field. |
Nimbu.Atomic.Increment(amount) | Increment a number. |
Nimbu.Atomic.Add(values) | Append array values. |
Nimbu.Atomic.AddUnique(values) | Append array values if missing. |
Nimbu.Atomic.Remove(values) | Remove array values. |
Nimbu.Atomic.Relation(adds, removes) | Add/remove relation references. |
Prefer object helpers such as increment() and relation().add() when they fit.
Files
Create files from bytes or base64 data:
const contract = new Nimbu.File('contract.pdf', {
base64: request.params.pdf
});
entry.set('contract', contract);
await entry.save();Remove an existing linked file:
const file = entry.file('contract');
if (file) {
file.remove();
await entry.save();
}Galleries
const gallery = entry.gallery('photos');
gallery.add([
new Nimbu.GalleryImage({
caption: 'Front view',
file: new Nimbu.File('front.jpg', { base64: frontImage })
})
]);
await entry.save();Read images:
const images = entry.gallery('photos').list();Select And Multiselect
By default, get() returns select values. Pass { options: true } when you need option objects.
const status = article.get('status');
const option = article.get('status', { options: true });For multiselect fields:
const values = article.get('topics');
const list = article.get('topics', { options: true });
list.addValue('Energy');
list.removeValue('Draft');
await article.save();