prepend operator

[AlexandrHoroshih]

Kudos to @Kelin2025 who is original author of this operator

Idea

This is basically upside-down version of sample, which returns callable clock event, instead of non-callable target

It can be very useful in many cases, like (very popular recently) guard + fn

guard({
  source: $some,
  clock: trigger,
  filter: $isValid,
  // wow! guard + fn!
  target: prepend({
    source: $another,
    fn: (another, target) => `${another} ${target}`,
    target: [submit, log]
  })
})

// more classic case
guard({
  source: $formValues,
  clock: trigger,
  filter: $isValid,
  // wow! guard + fn!
  target: prepend({
    source: trigger,
    fn: (trigger, values) => ({ values, eventName: trigger}),
    target: [submitFx, log]
  })
})

Or any case, where we might need to attach additional data to target:

spread({
  source: trigger,
  targets: {
    first: $first,
    second: prepend({
      source: $third,
      fn: (third, second) => doStuff(third, second),
      target: $second
    }),
  },
});

condition({
  source: trigger,
  if: (string) => string.length > 6,
  then: prepend<string>({
    source: $defaultLongString,
    target: longString
  }),
  else: shortString,
});

also it can serve as a more common version of attach operator, like this:

const pick = prepend<string>({
  source: $registry,
  fn: (registry, id) => registry[id],
  target: $picked
})

UPD: actually, it is not exactly like attach 🤔, more like event defined together with some data-flow part

Try it

Caveats

Due to lack of support for this kind of type inference in TypeScript it will be almost always necessary to set correct payload type via generic, like this:

prepend<StoreValue<typeof $some>>({
    source: $another,
    fn: (another, target) => `${another} ${target}`,
    target: [submit, log]
  })

Which is similar to usage of event.prepend

[Kelin2025]

Yeah, prepend is really useful, especially when working with forest:

list($tasks, ({ store: $task, key: $idx }) => {
  h("input", {
    attr: { value: $task },
    handler: { 
      change: prepend<InputEvent>({
        source: $idx, 
        target: taskChanged, 
        fn: (idx, evt) => ({ idx, value: evt.target.value })
      }) 
    }
  })
})

Also, I'd recommend to support a shorthand as well:

prepend($idx, taskChanged, (idx, evt) => ({ idx, value: evt.target.value }))

[AlexandrHoroshih]

Another possbile use-case - write to stores from multitarget sample

sample({
 source: ...,
 clock: ...,
 fn: () => {
  ...
  return {
    dataOne: "bla",
    dataTwo: "kek"
  }
 },
 target: [
  prepend({ fn: (d) => d.dataOne, target: $storeOne }),
  prepend({ fn: (d) => d.dataTwo, target: $storeTwo })
 ]
})

Maybe, even some shorthand overload would be useful

prepend($store, (data) => data.dataOne)
// or other unit
prepend(event, (data) => data.dataOne)

[igorkamyshev]

Isn't this use case covered by 'spread'?

[AlexandrHoroshih]

With prepend you can apply some custom data transformation before writing into store

spread({
  source: trigger,
  targets: {
    // $first will be target with this overload
    first: prepend($first, (triggerFirstData) => doStuff(triggerFirstData)),
    second: prepend({
      source: $third,
      fn: (third, second) => doStuff(third, second),
      target: $second
    }),
  },
});

[AlexandrHoroshih]

Another case: split with multiple cases + data mapping

split({
  source: filterBy,
  match: {
    all: msg => msg === 'all',
    new: msg => msg === 'new',
  },
  cases: {
    all: prepend($all, (list) => Object.keys(list).map(key => list[key]).flat()),
    new: prepend({
      source: $user,
      fn: (user, list) => Object.keys(list).map(key => list[key]).flat().filter(entity => entity.userId === user.id),
      target: $otherStore
    })
  }
})