HeapTableRepo.updateMaybe

A non-strict version of update. It 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 "non-strict" - if there is no record with the given ID in the table, it returns null.

Usage/Signature

table.updateMaybe(ctx, idAndFieldsToUpdate)

• Arguments

  • ctx*: app.Ctx
    The request context. Used for internal implementation, to save 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 conform 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 keeping 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, or null if there was no record with such an ID.

Examples

Simple field modification with handling the case of a non-existent record

const Tasks = Heap.Table('tasks', {
  title: Heap.String(),
  priority: Heap.NonRequired(Heap.Integer(), 3),
})

const updatedTask = await Tasks.updateMaybe(ctx, { id: req.params.id, priority: 0 })
if (!updatedTask) { 
  throw `task ${req.params.id} not found!`
}

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.updateMaybe(ctx, { id: newTask.id, description: null })
/* {
     title: 'Call the client',
   } */

Demonstrating the behavior of an Optional field when modifying 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.updateMaybe(ctx, {
  id: newTask.id,
  customerInfo: {
    name: 'Ivan Petrov',
  },
})
/* {
     title: 'Call the client',
     customerInfo: {
       name: 'Ivan Petrov',
     },
   } */