Relations & Field Types

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();