id

package

v1.10.0 Latest Latest Go to latest Published: Nov 2, 2026 License: MIT Imports: 4 Imported by: 1

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/xraph/herald

Links

Open Source Insights

Documentation ¶

Overview ¶

Package id defines TypeID-based identity types for all Herald entities.

Every entity in Herald uses a single ID struct with a prefix that identifies the entity type. IDs are K-sortable (UUIDv7-based), globally unique, and URL-safe in the format "prefix_suffix".

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type DeviceID ¶

type DeviceID = ID

DeviceID identifies a registered device.

type ID ¶

type ID struct {
	// contains filtered or unexported fields
}

ID is the primary identifier type for all Herald entities. It wraps a TypeID providing a prefix-qualified, globally unique, sortable, URL-safe identifier in the format "prefix_suffix".

var Nil ID

Nil is the zero-value ID.

func MustParse ¶

func MustParse(s string) ID

MustParse is like Parse but panics on error. Use for hardcoded ID values.

func New ¶

func New(prefix Prefix) ID

New generates a new globally unique ID with the given prefix. It panics if prefix is not a valid TypeID prefix (programming error).

func NewDeviceID ¶

func NewDeviceID() ID

NewDeviceID generates a new unique device ID.

func NewInboxID ¶

func NewInboxID() ID

NewInboxID generates a new unique in-app notification ID.

func NewMessageID ¶

func NewMessageID() ID

NewMessageID generates a new unique message ID.

func NewPreferenceID ¶

func NewPreferenceID() ID

NewPreferenceID generates a new unique preference ID.

func NewProviderID ¶

func NewProviderID() ID

NewProviderID generates a new unique provider ID.

func NewScopedConfigID ¶

func NewScopedConfigID() ID

NewScopedConfigID generates a new unique scoped config ID.

func NewTemplateID ¶

func NewTemplateID() ID

NewTemplateID generates a new unique template ID.

func NewTemplateVersionID ¶

func NewTemplateVersionID() ID

NewTemplateVersionID generates a new unique template version ID.

func Parse ¶

func Parse(s string) (ID, error)

Parse parses a TypeID string into an ID. Returns an error if the string is not valid.

func ParseAny ¶

func ParseAny(s string) (ID, error)

ParseAny parses a string into an ID without type checking the prefix.

func ParseDeviceID ¶

func ParseDeviceID(s string) (ID, error)

ParseDeviceID parses a string and validates the device prefix.

func ParseInboxID ¶

func ParseInboxID(s string) (ID, error)

ParseInboxID parses a string and validates the inbox prefix.

func ParseMessageID ¶

func ParseMessageID(s string) (ID, error)

ParseMessageID parses a string and validates the message prefix.

func ParsePreferenceID ¶

func ParsePreferenceID(s string) (ID, error)

ParsePreferenceID parses a string and validates the preference prefix.

func ParseProviderID ¶

func ParseProviderID(s string) (ID, error)

ParseProviderID parses a string and validates the provider prefix.

func ParseScopedConfigID ¶

func ParseScopedConfigID(s string) (ID, error)

ParseScopedConfigID parses a string and validates the scoped config prefix.

func ParseTemplateID ¶

func ParseTemplateID(s string) (ID, error)

ParseTemplateID parses a string and validates the template prefix.

func ParseTemplateVersionID ¶

func ParseTemplateVersionID(s string) (ID, error)

ParseTemplateVersionID parses a string and validates the template version prefix.

func ParseWithPrefix ¶

func ParseWithPrefix(s string, expected Prefix) (ID, error)

ParseWithPrefix parses a TypeID string and validates that its prefix matches the expected value.

func (ID) IsNil ¶

func (i ID) IsNil() bool

IsNil reports whether this ID is the zero value.

func (ID) MarshalBSONValue ¶

func (i ID) MarshalBSONValue() (bsonType byte, data []byte, err error)

MarshalBSONValue satisfies bson.ValueMarshaler (mongo-driver v2) so the ID is stored as a BSON string instead of an opaque struct.

func (ID) MarshalText ¶

func (i ID) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (ID) Prefix ¶

func (i ID) Prefix() Prefix

Prefix returns the prefix component of this ID.

func (*ID) Scan ¶

func (i *ID) Scan(src any) error

Scan implements sql.Scanner for database retrieval.

func (ID) String ¶

func (i ID) String() string

String returns the full TypeID string representation (prefix_suffix). Returns an empty string for the Nil ID.

func (*ID) UnmarshalBSONValue ¶

func (i *ID) UnmarshalBSONValue(t byte, data []byte) error

UnmarshalBSONValue satisfies bson.ValueUnmarshaler (mongo-driver v2).

func (*ID) UnmarshalText ¶

func (i *ID) UnmarshalText(data []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

func (ID) Value ¶

func (i ID) Value() (driver.Value, error)

Value implements driver.Valuer for database storage. Returns nil for the Nil ID so that optional foreign key columns store NULL.

type InboxID ¶

type InboxID = ID

InboxID identifies an in-app notification.

type MessageID ¶

type MessageID = ID

MessageID identifies a sent/queued notification message.

type PreferenceID ¶

type PreferenceID = ID

PreferenceID identifies a user's notification preferences.

type Prefix ¶

type Prefix string

Prefix identifies the entity type encoded in a TypeID.

const (
	PrefixProvider        Prefix = "hpvd"
	PrefixTemplate        Prefix = "htpl"
	PrefixTemplateVersion Prefix = "htpv"
	PrefixMessage         Prefix = "hmsg"
	PrefixInbox           Prefix = "hinb"
	PrefixPreference      Prefix = "hprf"
	PrefixScopedConfig    Prefix = "hscf"
	PrefixDevice          Prefix = "hdev"
)