brand

package
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package brand provides branded types to prevent mixing raw strings or bytes across package contracts, matching util/id-brand and util/bytes upstream.

Branded[T] uses empty tag types to distinguish SessionID, ToolCallID, and other identifiers at compile time. Concrete aliases inherit serialization, database, and comparison methods. Construct them with NewSessionID, ParseSessionID, and similar helpers; brand.New[brand.SessionID] would incorrectly nest wrappers. Cross-package contracts should use these concrete types instead of raw values.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ApprovalRequestID

type ApprovalRequestID = Branded[approvalRequestIDTag]

ApprovalRequestID uniquely identifies an approval prompt.

func NewApprovalRequestID

func NewApprovalRequestID(raw string) ApprovalRequestID

NewApprovalRequestID constructs an approval request ID.

func ParseApprovalRequestID

func ParseApprovalRequestID(raw string) (ApprovalRequestID, error)

ParseApprovalRequestID parses and validates an approval request ID.

type AttachmentID

type AttachmentID = Branded[attachmentIDTag]

AttachmentID identifies an image or file in attachment storage.

func NewAttachmentID

func NewAttachmentID(raw string) AttachmentID

NewAttachmentID constructs an attachment ID.

func ParseAttachmentID

func ParseAttachmentID(raw string) (AttachmentID, error)

ParseAttachmentID parses and validates an attachment ID.

type Branded

type Branded[T comparable] struct {
	// contains filtered or unexported fields
}

Branded carries a string with a compile-time tag T. Distinct tags produce incompatible ID types, preventing a SessionID from being used as a ToolCallID. The unexported value is initialized through constructors or UnmarshalJSON.

func (Branded[T]) Equal

func (b Branded[T]) Equal(other Branded[T]) bool

Equal compares IDs with the same brand; incompatible brands cannot be compared.

func (Branded[T]) IsZero

func (b Branded[T]) IsZero() bool

IsZero reports whether the value is unset or empty.

func (Branded[T]) MarshalJSON

func (b Branded[T]) MarshalJSON() ([]byte, error)

MarshalJSON encodes the ID as a JSON string.

func (Branded[T]) Raw

func (b Branded[T]) Raw() string

Raw returns the underlying string for external boundaries such as logs and filesystem paths. Cross-package contracts should retain the branded type.

func (*Branded[T]) Scan

func (b *Branded[T]) Scan(src any) error

Scan implements sql.Scanner for string, []byte, and nil values.

func (Branded[T]) String

func (b Branded[T]) String() string

String returns the underlying string and implements fmt.Stringer.

func (*Branded[T]) UnmarshalJSON

func (b *Branded[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a JSON string into the branded ID.

func (Branded[T]) Value

func (b Branded[T]) Value() (driver.Value, error)

Value implements driver.Valuer for persistence.

type Bytes

type Bytes[T comparable] struct {
	// contains filtered or unexported fields
}

Bytes carries binary data such as attachments and large tool results. Empty tag types distinguish different byte semantics at compile time.

func NewBytes

func NewBytes[T comparable](raw []byte) Bytes[T]

NewBytes wraps a byte slice; the caller must not mutate it afterward.

func ZeroBytes

func ZeroBytes[T comparable]() Bytes[T]

ZeroBytes returns zero-value branded bytes.

func (Bytes[T]) Bytes

func (b Bytes[T]) Bytes() []byte

Bytes returns a view of the underlying byte slice.

func (Bytes[T]) IsZero

func (b Bytes[T]) IsZero() bool

IsZero reports an empty or unset slice.

func (Bytes[T]) Len

func (b Bytes[T]) Len() int

Len returns the underlying byte length.

func (Bytes[T]) MarshalJSON

func (b Bytes[T]) MarshalJSON() ([]byte, error)

MarshalJSON encodes branded bytes as a base64 JSON string.

func (Bytes[T]) String

func (b Bytes[T]) String() string

String returns the UTF-8 string view, useful for text such as tool results.

func (*Bytes[T]) UnmarshalJSON

func (b *Bytes[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a base64 JSON string into branded bytes.

type CredentialRef

type CredentialRef = Branded[credentialRefTag]

CredentialRef brands a POSIX variable name, such as OPENAI_API_KEY.

func NewCredentialRef

func NewCredentialRef(raw string) CredentialRef

NewCredentialRef constructs a credential reference.

func ParseCredentialRef

func ParseCredentialRef(raw string) (CredentialRef, error)

ParseCredentialRef parses and validates a credential reference.

type JobID

type JobID = Branded[jobIDTag]

JobID uniquely identifies a background runtime job.

func NewJobID

func NewJobID(raw string) JobID

NewJobID constructs a background job ID.

func ParseJobID

func ParseJobID(raw string) (JobID, error)

ParseJobID parses and validates a job ID.

type ProjectionID

type ProjectionID = Branded[projectionIDTag]

ProjectionID identifies a registered session projection.

func NewProjectionID

func NewProjectionID(raw string) ProjectionID

NewProjectionID constructs a projection ID.

func ParseProjectionID

func ParseProjectionID(raw string) (ProjectionID, error)

ParseProjectionID parses and validates a projection ID.

type SessionID

type SessionID = Branded[sessionIDTag]

SessionID uniquely identifies an event-sourced SessionLog.

func NewSessionID

func NewSessionID(raw string) SessionID

NewSessionID constructs a session ID from a raw string.

func ParseSessionID

func ParseSessionID(raw string) (SessionID, error)

ParseSessionID validates a session ID, rejecting empty strings.

type SkillID

type SkillID = Branded[skillIDTag]

SkillID identifies a skill in the six-layer registry.

func NewSkillID

func NewSkillID(raw string) SkillID

NewSkillID constructs a skill ID.

func ParseSkillID

func ParseSkillID(raw string) (SkillID, error)

ParseSkillID parses and validates a skill ID.

type ToolCallID

type ToolCallID = Branded[toolCallIDTag]

ToolCallID pairs a tool/call event with its tool/result.

func NewToolCallID

func NewToolCallID(raw string) ToolCallID

NewToolCallID constructs a tool call ID from a raw string.

func ParseToolCallID

func ParseToolCallID(raw string) (ToolCallID, error)

ParseToolCallID parses and validates a tool call ID.

type WorkspaceID

type WorkspaceID = Branded[workspaceIDTag]

WorkspaceID identifies a directory in the workspace registry.

func NewWorkspaceID

func NewWorkspaceID(raw string) WorkspaceID

NewWorkspaceID constructs a workspace ID.

func ParseWorkspaceID

func ParseWorkspaceID(raw string) (WorkspaceID, error)

ParseWorkspaceID parses and validates a workspace ID.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL