Hook and value performance

Hooks and validators run inside the operation that triggered them. Their database calls, network waits, scans, and allocations therefore become part of save or read latency. Repeated fields add one callback occurrence per matching row or block, so callback work should usually be proportional to the value it handles.

Choose the cheapest correct phase

Keep external network work out of pre-commit phases unless its success is truly required before the document commits. Pass ctx.Context to every database or network call so cancellation and deadlines stop work the caller no longer needs.

Return Keep for an unchanged field

Ridu tracks immutable value backing through operation passes. Returning operation.Keep lets it retain the current branch. Do not return an equal replacement merely to signal success.

package content

import (
  "strings"

  "github.com/riducms/ridu/field"
  "github.com/riducms/ridu/operation"
)

func trimTitle(
  _ operation.WriteContext,
  value operation.Value[string],
) (operation.Change[string], error) {
  title, present := value.Get()
  if !present {
    return operation.Keep[string](), nil
  }
  trimmed := strings.TrimSpace(title)
  if trimmed == title {
    // Keep preserves the current immutable value and avoids replacement work.
    return operation.Keep[string](), nil
  }
  return operation.Replace(operation.Present(trimmed)), nil
}

var Title = field.Text("title").Hooks(field.Hooks[string]{
  BeforeChange: []field.Transform[string]{trimTitle},
})

Read immutable values without copying

operation.View and nested store.Value containers are immutable snapshots. Reading them is safe without defensive copies. Follow one object member at a time and iterate lists directly:

package content

import "github.com/riducms/ridu/operation"

func countNamedLinks(ctx operation.Context) int {
  links := ctx.Root.Get("links")
  count := 0
  for item := range links.Elements() {
    label, ok := item.Get("label").StringValue()
    if ok && label != "" {
      count++
    }
  }
  return count
}

Use a Copy... method at the point where another API requires a mutable Go container or where you intend to edit it. Repeatedly calling CopyList or CopyObject inside a loop materializes the same container again. The top-level store.Values map is mutable Go state; call store.CloneValues before editing a separate top-level copy.

Keep embedded callbacks linear

A field hook attached inside an array, Blocks field, or plugin-declared embedded tree runs for each matching occurrence. Ridu now traverses each embedded tree in a batch and applies scalar replacements without cloning the whole enclosing list each time. Application code can still turn a linear operation into quadratic work by rescanning the complete root list from every row callback.

Stable row keys identify retained array and block occurrences after reordering. Use ctx.Siblings and ctx.Prior rather than searching by the current array index. Shared block definitions share schema metadata; their access rules and hooks still run independently at each placement and occurrence.

Avoid repeated reads inside one callback

ctx.Local.FindByID preserves the actor, exact locale, cancellation, and active transaction. Ridu does not promise an application-level memoized result for arbitrary callback reads. If several checks in one callback need the same target, read it once and reuse the returned immutable document. If many occurrences need the same lookup, reconsider whether one resource hook can do the work once.

Do not hide mutable cross-request caches inside field definitions. If a cache is necessary, define its authorization dimensions, size bound, expiration, invalidation, and concurrency behavior, then measure it under the expected workload.

Reuse block definitions

Register a block once when several fields use the same schema. References also controls the picker order for that field:

package content

import (
  "github.com/riducms/ridu"
  "github.com/riducms/ridu/field"
)

var Hero = field.Block{
  Slug: "hero",
  Fields: field.Fields{
    field.Text("heading").Required(),
    field.Textarea("summary"),
  },
}

func Config() ridu.Config {
  return ridu.Config{
    Name:   "Editorial",
    Blocks: []field.Block{Hero},
    Collections: []ridu.Collection{{
      Slug: "pages",
      Fields: field.Fields{
        field.Blocks("layout").References("hero"),
      },
    }},
  }
}

Use inline field.Blocks("layout", Hero) when a definition belongs to one field. Do not register and inline the same slug on one field. See Blocks for labels, localization, migrations, and generated types.

Profile before introducing a cache

Start with a CPU and allocation profile of the actual operation. A cache cannot fix an O(N²) callback, an unnecessary copy, or a response that populates unused content. It can also retain caller-specific documents longer than expected. Measure performance shows the repository benchmark commands and the measurements to collect for an application.