types.go

// Copyright 2025 U. Cirello, cirello.io/types
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the “Software”), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.

// Package types provides linear and affine types that can be used to ensure that
// values are used exactly once or at most once. This is useful for managing
// resources and ensuring that they are not used after they have been released.
//
// This package uses panics to indicate that a certain type has been used
// incorrectly, and therefore it should indicate that somewhere there is a
// correctness issue in need of fix.
package types // import "cirello.io/types"

import (
	"runtime"
)

// LinearTypeGC is a linear typed value that can only be used once. It relied on
// runtime.AddCleanup to ensure that the value is used exactly once.
type LinearTypeGC[T any] struct {
	ch chan T
}

func LinearGC[T any](v T) *LinearTypeGC[T] {
	ch := make(chan T, 1)
	ch <- v
	res := &LinearTypeGC[T]{ch: ch}
	runtime.AddCleanup(res, func(ch chan T) {
		select {
		case <-ch:
			panic("value not used")
		default:
		}
	}, ch)
	return res
}

// Unwrap returns the value and ensures that it is used exactly once.
func (l *LinearTypeGC[T]) Unwrap() T {
	if l == nil || l.ch == nil {
		panic("uninitialized linear typed value")
	}
	select {
	case v := <-l.ch:
		return v
	default:
		panic("value already consumed")
	}
}

// LinearDeferType is a linear typed value that can only be used once. You must
// call Check and the end of expected lifetime of the value to ensure that it is
// used exactly once.
type LinearDeferType[T any] struct {
	ch chan T
}

func Linear[T any](v T) *LinearDeferType[T] {
	ch := make(chan T, 1)
	ch <- v
	res := &LinearDeferType[T]{ch: ch}
	return res
}

// Unwrap returns the value and ensures that it is used exactly once.
func (l *LinearDeferType[T]) Unwrap() T {
	if l == nil || l.ch == nil {
		panic("uninitialized linear typed value")
	}
	select {
	case v := <-l.ch:
		return v
	default:
		panic("value already consumed")
	}
}

func (l *LinearDeferType[T]) Check() {
	if l == nil || l.ch == nil {
		panic("uninitialized linear typed value")
	}
	select {
	case <-l.ch:
		panic("value not consumed")
	default:
	}
}

// Affine is a affine typed value that can be at most used once.
type Affine[T any] struct {
	ch chan T
}

func NewAffine[T any](v T) *Affine[T] {
	ch := make(chan T, 1)
	ch <- v
	res := &Affine[T]{ch: ch}
	return res
}

// Unwrap returns the value and ensures that it is used at most once.
func (a *Affine[T]) Unwrap() T {
	if a == nil || a.ch == nil {
		panic("uninitialized affine typed value")
	}
	select {
	case v := <-a.ch:
		return v
	default:
		panic("value already consumed")
	}
}