HeapTableRepo.update

Edits the specified top-level fields in a heap table record with the given ID.

New field values are validated against the table schema.

The method is "strict" - it throws an exception if there is no record with the given ID in the table.

Usage/Signature

table.update(ctx, idAndFieldsToUpdate)

Arguments
- ctx*: app.Ctx
  Request context. Used for internal implementation, saving information about the user who modified the record, and allows executing the request in the appropriate transaction.
- idAndFieldsToUpdate: { id: string, ... }
  
  An object containing the ID of the record to be changed and the new field values.
  
  Only the id field is mandatory. Along with it, only those fields whose values need to be changed should be specified. The names and values of the provided fields must correspond to the heap table schema.
  
  Unlike the create operation, default values do NOT apply here even for nested objects, meaning that if you need to change a nested object, you must provide it completely with all filled fields (you can omit an Optional field if you really want to reset its value to undefined, rather than keep the old one).
  
  If you pass a value of null to an Optional field, it will be reset to undefined. This is a special exception for Optional fields, as the value undefined means "do nothing" and does not allow resetting the field's value.
Return Value: Promise<HeapObject>
- The just modified heap object.

Examples

Simple change of the `priority` field

const Tasks = Heap.Table('tasks', {
  title: Heap.String(),
  priority: Heap.NonRequired(Heap.Integer(), 3),
})
const newTask = await Tasks.create(ctx, { title: 'Call the client' })
/* {
     title: 'Call the client',
     priority: 3,
   } */

const updatedTask = await Tasks.update(ctx, { id: newTask.id, priority: 0 })
/* {
     title: 'Call the client',
     priority: 0,
   } */

Resetting the Optional field `description`

const Tasks = Heap.Table('tasks', {
  title: Heap.String(),
  description: Heap.Optional(Heap.String()),
})
const newTask = await Tasks.create(ctx, {
  title: 'Call the client',
  description: 'Description',
})
/* {
     title: 'Call the client',
     description: 'Description',
   } */

const updatedTask = await Tasks.update(ctx, { id: newTask.id, description: null })
/* {
     title: 'Call the client',
   } */

Demonstrating the behavior of the Optional field when changing a nested object

const Tasks = Heap.Table('tasks', {
  title: Heap.String(),
  customerInfo: Heap.Optional(Heap.Object({
    name: Heap.String(),
    email: Heap.Optional(Heap.String({ format: 'email' })),
  })),
})
const newTask = await Tasks.create(ctx, {
  title: 'Call the client',
  customerInfo: {
    name: 'Ivan Petrov',
    email: 'ivan@example.com',
  },
})
/* {
     title: 'Call the client',
     customerInfo: {
       name: 'Ivan Petrov',
       email: 'ivan@example.com',
     },
   } */

const updatedTask = await Tasks.update(ctx, {
  id: newTask.id,
  customerInfo: {
    name: 'Ivan Petrov',
  },
})
/* {
     title: 'Call the client',
     customerInfo: {
       name: 'Ivan Petrov',
     },
   } */