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();Nimbu.File sends the file as base64 inside the save. For large files or browser uploads, upload
straight to storage instead: Direct File Uploads shows the flow with
Nimbu.API.
A file or gallery field can limit the size and the kinds of files it takes (max_file_size,
allowed_file_types). Customers and anonymous visitors are also held to a 50 MB cap and can't
upload SVG or "Other" files unless the field allows them. A file outside those limits makes save()
fail with a validation error on the field. See
Upload limits on file and gallery fields.
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();