uuidify

package module
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2025 License: MIT Imports: 1 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 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.

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