StoreSideEffects

Public class

The side effect manager (aka a "correct state enforcer") is responsible for making sure that the editor's state is always correct. This includes things like: deleting a shape if its parent is deleted; unbinding arrows when their binding target is deleted; etc.

class StoreSideEffects<R extends UnknownRecord> {}

UnknownRecord

packages/store/src/lib/StoreSideEffects.ts

Constructor

Public constructor

Constructs a new instance of the StoreSideEffects class

Store<R>

Store

Methods

registerAfterChangeHandler()

Public method

Register a handler to be called after a record is changed. This is useful for side-effects that would update other records - if you want to modify the record being changed, use StoreSideEffects.registerBeforeChangeHandler instead.

editor.sideEffects.registerAfterChangeHandler('shape', (prev, next, source) => {
  if (next.props.color === 'red') {
    // there can only be one red shape at a time:
    const otherRedShapes = editor
      .getCurrentPageShapes()
      .filter((s) => s.props.color === 'red' && s.id !== next.id)
    editor.updateShapes(
      otherRedShapes.map((s) => ({
        ...s,
        props: { ...s.props, color: 'blue' },
      }))
    )
  }
})

registerAfterChangeHandler<T extends R['typeName']>(
  typeName: T,
  handler: StoreAfterChangeHandler<
    R & {
      typeName: T
    }
  >
): () => void

T

StoreAfterChangeHandler<
  R & {
    typeName: T
  }
>

() => void

StoreAfterChangeHandler

registerAfterCreateHandler()

Public method

Register a handler to be called after a record is created. This is useful for side-effects that would update other records. If you want to modify the record being created use StoreSideEffects.registerBeforeCreateHandler instead.

editor.sideEffects.registerAfterCreateHandler('page', (page, source) => {
  // Automatically create a shape when a page is created
  editor.createShape({
    id: createShapeId(),
    type: 'text',
    props: { text: page.name },
  })
})

registerAfterCreateHandler<T extends R['typeName']>(
  typeName: T,
  handler: StoreAfterCreateHandler<
    R & {
      typeName: T
    }
  >
): () => void

T

StoreAfterCreateHandler<
  R & {
    typeName: T
  }
>

() => void

StoreAfterCreateHandler

registerAfterDeleteHandler()

Public method

Register a handler to be called after a record is deleted. This is useful for side-effects that would update other records - if you want to block the deletion of the record itself, use StoreSideEffects.registerBeforeDeleteHandler instead.

editor.sideEffects.registerAfterDeleteHandler('shape', (shape, source) => {
  // if the last shape in a frame is deleted, delete the frame too:
  const parentFrame = editor.getShape(shape.parentId)
  if (!parentFrame || parentFrame.type !== 'frame') return

  const siblings = editor.getSortedChildIdsForParent(parentFrame)
  if (siblings.length === 0) {
    editor.deleteShape(parentFrame.id)
  }
})

registerAfterDeleteHandler<T extends R['typeName']>(
  typeName: T,
  handler: StoreAfterDeleteHandler<
    R & {
      typeName: T
    }
  >
): () => void

T

StoreAfterDeleteHandler<
  R & {
    typeName: T
  }
>

() => void

StoreAfterDeleteHandler

registerBeforeChangeHandler()

Public method

Register a handler to be called before a record is changed. The handler is given the old and new record - you can return a modified record to apply a different update, or the old record to block the update entirely.

Use this handler only for intercepting updates to the record itself. If you want to update other records in response to a change, use StoreSideEffects.registerAfterChangeHandler instead.

editor.sideEffects.registerBeforeChangeHandler(
  'shape',
  (prev, next, source) => {
    if (next.isLocked && !prev.isLocked) {
      // prevent shapes from ever being locked:
      return prev
    }
    // other types of change are allowed
    return next
  }
)

registerBeforeChangeHandler<T extends R['typeName']>(
  typeName: T,
  handler: StoreBeforeChangeHandler<
    R & {
      typeName: T
    }
  >
): () => void

T

StoreBeforeChangeHandler<
  R & {
    typeName: T
  }
>

() => void

StoreBeforeChangeHandler

registerBeforeCreateHandler()

Public method

Register a handler to be called before a record of a certain type is created. Return a modified record from the handler to change the record that will be created.

Use this handle only to modify the creation of the record itself. If you want to trigger a side-effect on a different record (for example, moving one shape when another is created), use StoreSideEffects.registerAfterCreateHandler instead.

editor.sideEffects.registerBeforeCreateHandler('shape', (shape, source) => {
  // only modify shapes created by the user
  if (source !== 'user') return shape

  //by default, arrow shapes have no label. Let's make sure they always have a label.
  if (shape.type === 'arrow') {
    return { ...shape, props: { ...shape.props, text: 'an arrow' } }
  }

  // other shapes get returned unmodified
  return shape
})

registerBeforeCreateHandler<T extends R['typeName']>(
  typeName: T,
  handler: StoreBeforeCreateHandler<
    R & {
      typeName: T
    }
  >
): () => void

T

StoreBeforeCreateHandler<
  R & {
    typeName: T
  }
>

() => void

StoreBeforeCreateHandler

registerBeforeDeleteHandler()

Public method

Register a handler to be called before a record is deleted. The handler can return false to prevent the deletion.

Use this handler only for intercepting deletions of the record itself. If you want to do something to other records in response to a deletion, use StoreSideEffects.registerAfterDeleteHandler instead.

editor.sideEffects.registerBeforeDeleteHandler('shape', (shape, source) => {
  if (shape.props.color === 'red') {
    // prevent red shapes from being deleted
    return false
  }
})

registerBeforeDeleteHandler<T extends R['typeName']>(
  typeName: T,
  handler: StoreBeforeDeleteHandler<
    R & {
      typeName: T
    }
  >
): () => void

T

StoreBeforeDeleteHandler<
  R & {
    typeName: T
  }
>

() => void

StoreBeforeDeleteHandler

registerOperationCompleteHandler()

Public method

Register a handler to be called when a store completes an atomic operation.

let count = 0

editor.sideEffects.registerOperationCompleteHandler(() => count++)

editor.selectAll()
expect(count).toBe(1)

editor.store.atomic(() => {
  editor.selectNone()
  editor.selectAll()
})

expect(count).toBe(2)

registerOperationCompleteHandler(
  handler: StoreOperationCompleteHandler
): () => void

StoreOperationCompleteHandler

() => void

StoreOperationCompleteHandler