uuidify

package module
v0.0.2 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2025 License: MIT Imports: 10 Imported by: 0

README

uuidify-go

Release Go SDK Tests OpenAPI Sync

Official Go SDK for uuidify.io offering fast UUID/ULID generation with a minimal, idiomatic API. The package ships as a single module (github.com/ilkereroglu/uuidify-go) and can be embedded in CLIs, services, and serverless functions without extra dependencies.

Features

  • Simple uuidify.NewClient() constructor with overridable base URL, HTTP client, and User-Agent
  • Support for UUID v1, v4, and v7 plus ULID generation (single or batched)
  • Context-aware requests with consistent error types for transport, API status, and JSON decoding issues
  • Example applications and CI pipelines to keep the SDK production-ready

Installation

go get github.com/ilkereroglu/uuidify-go

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/ilkereroglu/uuidify-go"
)

func main() {
    client := uuidify.NewClient()

    id, err := client.UUIDv4(context.Background())
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("UUID v4:", id)
}

Usage

Customizing the Client
client := uuidify.NewClient(
    uuidify.WithBaseURL("https://api.uuidify.io"),
    uuidify.WithUserAgent("my-app/1.0"),
)

The client exposes:

  • UUIDv1(ctx) / UUIDv4(ctx) / UUIDv7(ctx)
  • ULID(ctx)
  • UUIDBatch(ctx, version, count)
  • ULIDBatch(ctx, count) Each method respects the provided context.Context for cancellation and deadlines.
Error Handling

Three dedicated error types make it easy to react appropriately:

  • RequestError – network failures or invalid requests
  • APIError – non-2xx responses, including HTTP status code and message
  • DecodeError – JSON decoding failures

Use errors.As to branch on these errors:

var apiErr *uuidify.APIError
if errors.As(err, &apiErr) {
    fmt.Println("UUIDify returned status", apiErr.StatusCode)
}

Examples

Run the samples in the examples/ directory:

go run ./examples/uuid_v7_batch

OpenAPI & Code Generation

The openapi/ directory is auto-synced from the upstream uuidify repository via GitHub Actions. Custom templates under templates/ are used with oapi-codegen (see openapi/config.yaml) to regenerate the SDK (client.go, models.go, request.go).

Development

go vet ./...
go test ./...
go build ./...

A CI workflow (.github/workflows/test.yaml) runs lint, build, and tests on every PR and push. Use go test -tags live ./... to hit the production API when needed.

License

This project is licensed under the MIT License.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	StatusCode int
	Message    string
}

APIError captures non-successful HTTP responses from the UUIDify API.

func (*APIError) Error

func (e *APIError) Error() string

type Client

type Client struct {
	BaseURL    string
	HTTPClient *http.Client
	UserAgent  string
}

Client is a minimal UUIDify API client.

func NewClient

func NewClient(opts ...ClientOption) *Client

NewClient constructs a new Client, applying any provided options.

func (*Client) ULID

func (c *Client) ULID(ctx context.Context) (string, error)

ULID fetches a ULID value.

func (*Client) ULIDBatch

func (c *Client) ULIDBatch(ctx context.Context, count int) ([]string, error)

ULIDBatch fetches multiple ULIDs.

func (*Client) UUIDBatch

func (c *Client) UUIDBatch(ctx context.Context, version string, count int) ([]string, error)

UUIDBatch fetches multiple UUIDs of the given version.

func (*Client) UUIDv1

func (c *Client) UUIDv1(ctx context.Context) (string, error)

UUIDv1 fetches a UUID v1 value.

func (*Client) UUIDv4

func (c *Client) UUIDv4(ctx context.Context) (string, error)

UUIDv4 fetches a UUID v4 value.

func (*Client) UUIDv7

func (c *Client) UUIDv7(ctx context.Context) (string, error)

UUIDv7 fetches a UUID v7 value.

type ClientOption

type ClientOption func(*Client)

ClientOption configure a Client.

func WithBaseURL

func WithBaseURL(url string) ClientOption

WithBaseURL overrides the default base URL.

func WithHTTPClient

func WithHTTPClient(client *http.Client) ClientOption

WithHTTPClient overrides the default HTTP client.

func WithUserAgent

func WithUserAgent(ua string) ClientOption

WithUserAgent overrides the default User-Agent header value.

type DecodeError

type DecodeError struct {
	Err error
}

DecodeError wraps errors that occur while decoding API responses.

func (*DecodeError) Error

func (e *DecodeError) Error() string

func (*DecodeError) Unwrap

func (e *DecodeError) Unwrap() error

Unwrap allows DecodeError to participate in errors.Is/errors.As checks.

type RequestError

type RequestError struct {
	Err error
}

RequestError wraps lower-level request construction or transport errors.

func (*RequestError) Error

func (e *RequestError) Error() string

func (*RequestError) Unwrap

func (e *RequestError) Unwrap() error

Unwrap allows RequestError to expose the original error.

type ULIDListResponse

type ULIDListResponse struct {
	ULIDs []string `json:"ulids"`
}

ULIDListResponse represents a response returning multiple ULID values.

type ULIDResponse

type ULIDResponse struct {
	ULID string `json:"ulid"`
}

ULIDResponse represents a response returning a single ULID value.

type UUIDListResponse

type UUIDListResponse struct {
	UUIDs []string `json:"uuids"`
}

UUIDListResponse represents a response returning multiple UUID values.

type UUIDResponse

type UUIDResponse struct {
	UUID string `json:"uuid"`
}

UUIDResponse represents a response returning a single UUID value.

Directories

Path Synopsis
examples
ulid command
uuid_v4 command
uuid_v7_batch command

Jump to

Keyboard shortcuts

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