feat: add templ.Once function

[a-h]

No description provided.

[joerdav]

Is the decision to re-use the ss one made to avoid allocations?

Have you had any thought about the use of runtime.Caller to differentiate uses of templ.Once?

// Once is a component that renders its children once per context.
func Once() OnceComponent {
	_, fname, ln, _ := runtime.Caller(1)
	return OnceComponent{
		ID: fname + fmt.Sprint(ln),
	}
}

It could be cleaner, but I have a feeling it might not actually work with -ldflags="-s -w".

[a-h]

Yes, the idea was to reuse the existing map allocation, rather than introduce a new one. On the id usage, I thought that it might be the case that you'd want to use the same Once operation despite being in different packages, so runtime.Caller probably wouldn't work.

For example, you might have a github.com/templ-go/components/button and a github.com/templ-go/components/link package, that both need JQuery. You'd want to have some freedom to allocate them the same ID.

On the other hand, I don't like that it's possible for someone to pollute the global "once" cache with something that's under their control.

I wonder if the API design should default to runtime caller, but allow the cache to be overriden.

I did think about using a type. Something like this:

type onceObjectForMyPackage int

templ component() {
  templ.Once[onceObjectForMyPackage](onceObjectForMyPackage(0)) {
    <div>Hello</div>
  }
}

I thought that it could allow the caller to use a private type, therefore ensuring that no-one else could use the ID and block a script from running.

[joerdav]

For example, you might have a github.com/templ-go/components/button and a github.com/templ-go/components/link package, that both need JQuery. You'd want to have some freedom to allocate them the same ID.

In this case I would probably recommend something like:

package deps

templ JQuery() {
    templ.Once() {
        <script />
    }
}

package button

templ Button() {
    @deps.JQuery()
     <button>Press the button</button>
}

package link

templ Button() {
     @deps.JQuery()
     <a>Click the link</a>
}

[a-h]

Oh, that's a nice design! I like that.

[a-h]

I've updated the PR to demonstrate the use of private types so that clashes can be avoided.

I worry that runtime.Caller could be a bit magical, and would result in various weird bug reports with an API that is hard to change later. If you're dead against having a param at all, I think we'd need to do a POC and get some community feedback.

[joerdav]

Definitely not dead against it, I think the key may be the safest and more robust way as long as users don't accidentally clash the key. I do think that no params is more ergonomic, but maybe the cost of that is things being expected.

I tried to think about how we could make it more like sync.Once but came up with nothing.... this kind of thing:

type once templ.Once

templ component() {
  @once.Do() {
    <div>Hello</div>
  }
}

I'm not sure the implementation would be any better than no params though.

[a-h]

I think you're onto something. Defining a variable to lock something is the right way to think about it.

The variable can also be exported from a package, to have a multi-package lock. In the latest commit, I've made it so that you can hard code the ID yourself if you want, but if you don't, it's just a random string.

package once

var helloRenderLock = templ.MustNewRenderLock()

templ hello(label, name string) {
	@helloRenderLock.Once() {
		<script type="text/javascript">
			function hello(name) {
				alert('Hello, ' + name + '!');
			}
		</script>
	}
	<input type="button" value={ label } data-name={ name } onclick="hello(this.getAttribute('data-name'))"/>
}

templ render() {
	@hello("Hello User", "user")
	@hello("Hello World", "world")
}

I haven't updated the docs, but what do you think of that design?

[joerdav]

That seems much more ergonomic! I'm on the fence about "lock" but I can't think of a better name hah.

One final implementation to consider before locking in is pointers rather than IDs. The upside of this is the constructor won't error.

But, it removes the option to provide a string id.

// NewRenderLock proivdes a component that renders its children once per context.
func NewRenderLock() (once *RenderLock) {
	once = &RenderLock{}
	return once, nil
}

type RenderLock struct{}

func (o *RenderLock) Once() Component {
	return ComponentFunc(func(ctx context.Context, w io.Writer) (err error) {
		_, v := getContext(ctx)
		if v.getHasOnceBeenRendered(o) {
			return nil
		}
		v.setHasOnceBeenRendered(o)
		return GetChildren(ctx).Render(ctx, w)
	})
}

func (v *contextValue) setHasOnceBeenRendered(lock *RenderLock) {
	if v.locks == nil {
		v.locks = map[*RenderLock]struct{}{}
	}
	v.locks[lock] = struct{}{}
}

func (v *contextValue) getHasOnceBeenRendered(lock *RenderLock) (ok bool) {
	if v.locks == nil {
		v.locks = map[*RenderLock]struct{}{}
	}
	_, ok = v.locks[lock]
	return
}

[a-h]

I'm glad we thrashed this out. I think this is the one.

[joerdav]

This looks great, I think the API is really clean!

That's a sneaky gotcha, I knew this was the case for things like pointers to primitive values but not structs!

//  | Two distinct zero-size variables may
//  | have the same address in memory