emojid

README

Emoji-d

Have you ever looked at an int, squinted at a UUID, and thought: this primary key has absolutely no theatrical value?

Good news. The database did not ask for dignity.

emojid is a tiny Go package for using curated emoji strings as PostgreSQL IDs. It wraps a private string, validates that the value is made only from a small approved emoji alphabet, and implements the boring interfaces required to work with database/sql, JSON, text encoding, and sqlc.

This is not a UUID replacement. This is a small act of database whimsy with just enough engineering discipline to avoid becoming a production incident with merch.

What It Does

emojid.ID is a non-null, text-backed ID type for people who believe 🐱 deserves the same referential integrity as 42.

It is valid when:

• it is not empty
• it is valid UTF-8
• every rune is in the curated emoji alphabet

That means these are valid:

🐱
🦆
🦆🦆
🌮🔥
🍕🐢👀

And these are not:

hello
123
🐱abc
🇺🇸
👍🏽

The package intentionally does not support flags, skin-tone variants, zero-width-joiner emoji, or whatever Unicode machinery is required to make a family emoji hold hands consistently across three operating systems and a terminal emulator.

Why

Because sometimes you need to remember software can still be fun, and sometimes that means telling PostgreSQL that 🦆 is a serious business identifier.

Also, this is a surprisingly decent little learning project:

• custom Go domain types
• database/sql.Scanner
• driver.Valuer
• JSON marshaling
• text marshaling
• UTF-8 validation
• PostgreSQL domains
• sqlc type overrides
• letting the database enforce uniqueness like a responsible adult

AI Disclosure

This is not a vibe-coded project.

The core implementation was written deliberately, by a human, with tests and docs getting some AI assistance. AI also served as the project's sentient rubber duck: patient, occasionally useful, and strangely willing to discuss whether 🌮 is a better primary key digit than ⭐.

Database Shape

Recommended PostgreSQL setup:

create domain emoji_id as text;

create table objects (
  id emoji_id primary key,
  body text not null
);

The domain is still backed by text, so PostgreSQL can index it, compare it, join on it, and reject duplicate primary keys without needing to understand the bit.

sqlc Usage

Use normal SQL:

-- name: CreateObject :one
insert into objects (id, body)
values ($1, $2)
returning id, body;

Then configure sqlc to map the database type to your Go type:

overrides:
  - db_type: "emoji_id"
    go_type:
      import: "github.com/you/emojid"
      type: "ID"

Now generated code can accept and return emojid.ID directly.

The caller brings the ID:

CreateObject(ctx, emojid.Must("🐱"), "hello world")

If 🐱 is already taken, PostgreSQL rejects the insert. As it should. There can only be one cat. The database has spoken.

Interfaces

ID is designed to satisfy:

database/sql.Scanner
database/sql/driver.Valuer
encoding.TextMarshaler
encoding.TextUnmarshaler
encoding/json.Marshaler
encoding/json.Unmarshaler
fmt.Stringer

The important behavior:

• database values scan into ID
• query args bind as text
• JSON encodes as "🐱", not {"ID":"🐱"}
• text encoding uses the raw emoji string
• invalid zero values should not quietly sneak into the database

Curated Alphabet

Phase 1 uses exactly 32 supported emoji. Think of it as base-32, except the digits have attitude and one of them is cheese.

package emojid

// validRunes is a curated list of emojis that are allowed for use in IDs.
// Source: https://unicode.org/emoji/charts/full-emoji-list.html
var validRunes = map[rune]struct{}{
	'😀': {},
	'🚀': {},
	'🔥': {},
	'🍕': {},
	'😅': {},
	'😐': {},
	'🙄': {},
	'🤮': {},
	'🤠': {},
	'🌮': {},
	//10
	'😎': {},
	'💩': {},
	'👻': {},
	'😺': {},
	'🍝': {},
	'💯': {},
	'🖕': {},
	'👍': {},
	'💪': {},
	'👀': {},
	//20
	'🦆': {},
	'🦉': {},
	'🐔': {},
	'🐸': {},
	'🐢': {},
	'🐌': {},
	'🌭': {},
	'🌲': {},
	'🍄': {},
	'🍌': {},
	//30
	'🍆': {},
	'🧀': {},
}

Capacity, if you want to pretend this is a numbering system:

1 emoji  = 32 possible IDs
2 emoji  = 1,024 possible IDs
3 emoji  = 32,768 possible IDs
4 emoji  = 1,048,576 possible IDs
5 emoji  = 33,554,432 possible IDs
6 emoji  = 1,073,741,824 possible IDs

But Phase 1 does not generate IDs. You pick them. The database tells you when your vibes collide. This is called architecture.

Non-Goals

This package does not try to:

• generate IDs
• guarantee uniqueness before insert
• support nullable IDs
• support every Unicode emoji
• support skin tones or flags
• define semantic emoji ordering
• replace migrations, query builders, or your sense of judgment

Range queries may work because PostgreSQL can compare text and nobody can stop you:

where id between $1 and $2

But that means PostgreSQL text ordering, not “all emoji between duck and taco in the grand taxonomy of nonsense.” Please do not cite this package in court.

Philosophy

The database owns uniqueness.

The caller owns choosing the ID.

emojid owns one tiny invariant:

This string is made only of approved emoji runes.

That is enough. Anything more would risk turning a joke into enterprise software, and nobody needs an Emoji Identity Governance Committee.

Documentation

Index

• func Validate(value string) error
• type ID
  • func Must(value string) ID
  • func New(value string) (ID, error)
  • func (i *ID) IsValid() bool
  • func (i ID) MarshalJSON() ([]byte, error)
  • func (i ID) MarshalText() ([]byte, error)
  • func (i *ID) Scan(value any) error
  • func (i ID) String() string
  • func (i *ID) UnmarshalJSON(data []byte) error
  • func (i *ID) UnmarshalText(text []byte) error
  • func (i ID) Value() (driver.Value, error)

Functions

func Validate

func Validate(value string) error

Validate checks if the given string is a valid emoji ID.

Types

type ID

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

ID represents a unique identifier validated against a curated list of emojis.

func Must

func Must(value string) ID

Must creates a new ID from a string value. It panics if the value is not a valid emoji ID.

func New

func New(value string) (ID, error)

New creates a new ID from a string value. It returns an error if the value is not a valid emoji ID.

func (*ID) IsValid

func (i *ID) IsValid() bool

IsValid returns true if the ID has a non-empty value.

func (ID) MarshalJSON

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

MarshalJSON implements the json.Marshaler interface. It returns the JSON encoding of the ID.

func (ID) MarshalText

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

MarshalText implements the encoding.TextMarshaler interface. It returns the text representation of the ID.

func (*ID) Scan

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

Scan implements the sql.Scanner interface. It validates that the value is a string or []byte and matches the curated emoji list.

func (ID) String

func (i ID) String() string

String returns the string representation of the ID.

func (*ID) UnmarshalJSON

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

UnmarshalJSON implements the json.Unmarshaler interface. It validates the JSON-encoded data and stores the result in the ID.

func (*ID) UnmarshalText

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

UnmarshalText implements the encoding.TextUnmarshaler interface. It validates the text and stores the result in the ID.

func (ID) Value

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

Value implements the driver.Valuer interface. It returns the string value or an error if the value is not defined.