diff --git a/README.md b/README.md index f9a8b1a..0129155 100644 --- a/README.md +++ b/README.md @@ -28,12 +28,12 @@ The `publicid` package is designed to generate and validate unique, public-facin ### ID Lengths -- Default/Short IDs: 8 characters +- Default IDs: 8 characters - Long IDs: 12 characters ### Collision Resistance -- Default/Short IDs: 1% collision probability after generating 8 billion IDs at 25 IDs/hour (~10 years) +- Default IDs: 1% collision probability after generating 8 billion IDs at 25 IDs/hour (~10 years) - Long IDs: 1% collision probability after generating 8 billion IDs at 25 IDs/second (~10 years) ### Key Features @@ -63,12 +63,12 @@ To use the `publicid` package in your Go code, follow these steps: import "github.com/agentstation/publicid" ``` -2. Generate a short public ID (8 characters): +2. Generate a default public ID (8 characters): ```go id, _ := publicid.New() -fmt.Println("Generated short public ID:", id) -// Output: Generated short public ID: Ab3xY9pQ +fmt.Println("Generated default public ID:", id) +// Output: Generated default public ID: Ab3xY9pQ ``` 3. Generate a long public ID (12 characters): @@ -87,17 +87,17 @@ fmt.Println("Generated public ID within 5 attempts:", id) // Output: Generated public ID within 5 attempts: Kj2mN8qL ``` -5. Validate a short public ID: +5. Validate a default public ID: ```go -shortID := "Ab3xY9pQ" -err := publicid.Validate(shortID) +defaultID := "Ab3xY9pQ" +err := publicid.Validate(defaultID) if err != nil { - fmt.Println("Invalid short ID:", err) + fmt.Println("Invalid default ID:", err) } else { - fmt.Println("Valid short ID:", shortID) + fmt.Println("Valid default ID:", defaultID) } -// Output: Valid short ID: Ab3xY9pQ +// Output: Valid default ID: Ab3xY9pQ ``` 6. Validate a long public ID: @@ -127,6 +127,7 @@ Package publicid generates and validates NanoID strings designed to be publicly ## Index +- [Constants](<#constants>) - [func New\(opts ...Option\) \(string, error\)](<#New>) - [func NewLong\(opts ...Option\) \(string, error\)](<#NewLong>) - [func Validate\(id string\) error](<#Validate>) @@ -134,11 +135,34 @@ Package publicid generates and validates NanoID strings designed to be publicly - [type Option](<#Option>) - [func Alphabet\(a string\) Option](<#Alphabet>) - [func Attempts\(n int\) Option](<#Attempts>) - - [func Len\(n int\) Option](<#Len>) + - [func Len\(len int\) Option](<#Len>) + - [func Long\(\) Option](<#Long>) +## Constants + + + +```go +const ( + // DefaultAlphabet is the set of characters used for generating public IDs. + // It includes 0-9, A-Z, and a-z, providing a balance between uniqueness and readability. + DefaultAlphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz" + + // DefaultIDLength is the default length for public IDs. + // Set to 8 characters, it provides a 1% collision probability after generating + // 8 billion IDs at 25 IDs/hour over approximately 10 years, assuming the use of DefaultAlphabet. + DefaultIDLength = 8 + + // LongIDLength is the length for long public IDs. + // Set to 12 characters, it provides a 1% collision probability after generating + // 8 billion IDs at 25 IDs/second over approximately 10 years, assuming the use of DefaultAlphabet. + LongIDLength = 12 +) +``` + -## func [New]() +## func [New]() ```go func New(opts ...Option) (string, error) @@ -147,7 +171,7 @@ func New(opts ...Option) (string, error) New generates a unique nanoID with a length of 8 characters and the given options. -## func [NewLong]() +## func [NewLong]() ```go func NewLong(opts ...Option) (string, error) @@ -156,7 +180,7 @@ func NewLong(opts ...Option) (string, error) NewLong generates a unique nanoID with a length of 12 characters and the given options. -## func [Validate]() +## func [Validate]() ```go func Validate(id string) error @@ -165,7 +189,7 @@ func Validate(id string) error Validate checks if a given field name's public ID value is valid according to the constraints defined by package publicid. -## func [ValidateLong]() +## func [ValidateLong]() ```go func ValidateLong(id string) error @@ -174,7 +198,7 @@ func ValidateLong(id string) error validateLong checks if a given field name's public ID value is valid according to the constraints defined by package publicid. -## type [Option]() +## type [Option]() Option is a function type for configuring ID generation. @@ -183,7 +207,7 @@ type Option func(*config) ``` -### func [Alphabet]() +### func [Alphabet]() ```go func Alphabet(a string) Option @@ -192,7 +216,7 @@ func Alphabet(a string) Option Alphabet returns an Option to set the alphabet to be used for ID generation. -### func [Attempts]() +### func [Attempts]() ```go func Attempts(n int) Option @@ -201,14 +225,23 @@ func Attempts(n int) Option Attempts returns an Option to set the number of attempts for ID generation. -### func [Len]() +### func [Len]() ```go -func Len(n int) Option +func Len(len int) Option ``` Len returns an Option to set the length of the ID to be generated. + +### func [Long]() + +```go +func Long() Option +``` + +Long returns an Option to set the length of the ID to be generated to 12. + Generated by [gomarkdoc]() diff --git a/publicid.go b/publicid.go index 0523a88..593020e 100644 --- a/publicid.go +++ b/publicid.go @@ -9,9 +9,19 @@ import ( ) const ( - alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz" - longLen = 12 - shortLen = 8 + // DefaultAlphabet is the set of characters used for generating public IDs. + // It includes 0-9, A-Z, and a-z, providing a balance between uniqueness and readability. + DefaultAlphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz" + + // DefaultIDLength is the default length for public IDs. + // Set to 8 characters, it provides a 1% collision probability after generating + // 8 billion IDs at 25 IDs/hour over approximately 10 years, assuming the use of DefaultAlphabet. + DefaultIDLength = 8 + + // LongIDLength is the length for long public IDs. + // Set to 12 characters, it provides a 1% collision probability after generating + // 8 billion IDs at 25 IDs/second over approximately 10 years, assuming the use of DefaultAlphabet. + LongIDLength = 12 ) // generator is the function used to generate nanoIDs. @@ -35,12 +45,17 @@ func Attempts(n int) Option { } // Len returns an Option to set the length of the ID to be generated. -func Len(n int) Option { +func Len(len int) Option { return func(c *config) { - c.length = n + c.length = len } } +// Long returns an Option to set the length of the ID to be generated to 12. +func Long() Option { + return Len(LongIDLength) +} + // Alphabet returns an Option to set the alphabet to be used for ID generation. func Alphabet(a string) Option { return func(c *config) { @@ -49,15 +64,15 @@ func Alphabet(a string) Option { } // New generates a unique nanoID with a length of 8 characters and the given options. -func New(opts ...Option) (string, error) { return generateID(shortLen, opts...) } +func New(opts ...Option) (string, error) { return generateID(DefaultIDLength, opts...) } // NewLong generates a unique nanoID with a length of 12 characters and the given options. -func NewLong(opts ...Option) (string, error) { return generateID(longLen, opts...) } +func NewLong(opts ...Option) (string, error) { return generateID(LongIDLength, opts...) } // generateID is a helper function to generate IDs with the given length and options. -func generateID(length int, opts ...Option) (string, error) { +func generateID(len int, opts ...Option) (string, error) { // set default configuration values - cfg := &config{attempts: 1, length: length, alphabet: alphabet} + cfg := &config{attempts: 1, length: len, alphabet: DefaultAlphabet} for _, opt := range opts { opt(cfg) } @@ -76,11 +91,16 @@ func generateID(length int, opts ...Option) (string, error) { // Validate checks if a given field name's public ID value is valid according to // the constraints defined by package publicid. -func Validate(id string) error { return validate(id, shortLen) } +func Validate(id string) error { return validate(id, DefaultIDLength) } // validateLong checks if a given field name's public ID value is valid according to // the constraints defined by package publicid. -func ValidateLong(id string) error { return validate(id, longLen) } +func ValidateLong(id string) error { return validate(id, LongIDLength) } + +// isValidChar checks if a given character is a valid public ID character. +func isValidChar(c rune) bool { + return (c >= '0' && c <= '9') || (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') +} // validate checks if a given public ID value is valid. func validate(id string, expectedLen int) error { @@ -97,8 +117,3 @@ func validate(id string, expectedLen int) error { } return nil // if we get here, the ID is valid } - -// isValidChar checks if a given character is a valid public ID character. -func isValidChar(c rune) bool { - return (c >= '0' && c <= '9') || (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') -}