uuidify

package module
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2025 License: MIT Imports: 8 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

Overview

Package uuidify provides primitives to interact with the openapi HTTP API.

Code generated by github.com/deepmap/oapi-codegen/v2 version v2.2.0 DO NOT EDIT.

Package uuidify provides primitives to interact with the openapi HTTP API.

Code generated by github.com/deepmap/oapi-codegen/v2 version v2.2.0 DO NOT EDIT.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewGetRequest added in v0.2.0

func NewGetRequest(server string, params *GetParams) (*http.Request, error)

NewGetRequest generates requests for Get

Types

type Client

type Client struct {
	// The endpoint of the server conforming to this interface, with scheme,
	// https://api.deepmap.com for example. This can contain a path relative
	// to the server, such as https://api.deepmap.com/dev-test, and all the
	// paths in the swagger spec will be appended to the server.
	Server string

	// Doer for performing requests, typically a *http.Client with any
	// customized settings, such as certificate chains.
	Client HttpRequestDoer

	// A list of callbacks for modifying requests which are generated before sending over
	// the network.
	RequestEditors []RequestEditorFn
}

Client which conforms to the OpenAPI3 specification for this service.

func NewClient

func NewClient(server string, opts ...ClientOption) (*Client, error)

Creates a new Client, with reasonable defaults

func (*Client) Get added in v0.2.0

func (c *Client) Get(ctx context.Context, params *GetParams, reqEditors ...RequestEditorFn) (*http.Response, error)

type ClientInterface added in v0.2.0

type ClientInterface interface {
	// Get request
	Get(ctx context.Context, params *GetParams, reqEditors ...RequestEditorFn) (*http.Response, error)
}

The interface specification for the client above.

type ClientOption

type ClientOption func(*Client) error

ClientOption allows setting custom parameters during construction

func WithBaseURL

func WithBaseURL(baseURL string) ClientOption

WithBaseURL overrides the baseURL.

func WithHTTPClient

func WithHTTPClient(doer HttpRequestDoer) ClientOption

WithHTTPClient allows overriding the default Doer, which is automatically created using http.Client. This is useful for tests.

func WithRequestEditorFn added in v0.2.0

func WithRequestEditorFn(fn RequestEditorFn) ClientOption

WithRequestEditorFn allows setting up a callback function, which will be called right before sending the request. This can be used to mutate the request.

type ClientWithResponses added in v0.2.0

type ClientWithResponses struct {
	ClientInterface
}

ClientWithResponses builds on ClientInterface to offer response payloads

func NewClientWithResponses added in v0.2.0

func NewClientWithResponses(server string, opts ...ClientOption) (*ClientWithResponses, error)

NewClientWithResponses creates a new ClientWithResponses, which wraps Client with return type handling

func (*ClientWithResponses) GetWithResponse added in v0.2.0

func (c *ClientWithResponses) GetWithResponse(ctx context.Context, params *GetParams, reqEditors ...RequestEditorFn) (*GetResponse, error)

GetWithResponse request returning *GetResponse

type ClientWithResponsesInterface added in v0.2.0

type ClientWithResponsesInterface interface {
	// GetWithResponse request
	GetWithResponse(ctx context.Context, params *GetParams, reqEditors ...RequestEditorFn) (*GetResponse, error)
}

ClientWithResponsesInterface is the interface specification for the client with responses above.

type GetParams added in v0.2.0

type GetParams struct {
	// Algorithm Generator algorithm selection
	Algorithm *GetParamsAlgorithm `form:"algorithm,omitempty" json:"algorithm,omitempty"`

	// Version UUID version.
	// When algorithm=ulid, version is ignored and ULIDs are produced.
	Version *GetParamsVersion `form:"version,omitempty" json:"version,omitempty"`

	// Count Number of identifiers to generate.
	Count *int `form:"count,omitempty" json:"count,omitempty"`

	// Format Response format.
	// - `json` → default structured JSON
	// - `text` → newline-delimited plaintext output
	Format *GetParamsFormat `form:"format,omitempty" json:"format,omitempty"`
}

GetParams defines parameters for Get.

type GetParamsAlgorithm added in v0.2.0

type GetParamsAlgorithm string

GetParamsAlgorithm defines parameters for Get.

const (
	GetParamsAlgorithmUlid GetParamsAlgorithm = "ulid"
	GetParamsAlgorithmUuid GetParamsAlgorithm = "uuid"
)

Defines values for GetParamsAlgorithm.

type GetParamsFormat added in v0.2.0

type GetParamsFormat string

GetParamsFormat defines parameters for Get.

const (
	Json GetParamsFormat = "json"
	Text GetParamsFormat = "text"
)

Defines values for GetParamsFormat.

type GetParamsVersion added in v0.2.0

type GetParamsVersion string

GetParamsVersion defines parameters for Get.

const (
	GetParamsVersionUlid GetParamsVersion = "ulid"
	GetParamsVersionV1   GetParamsVersion = "v1"
	GetParamsVersionV4   GetParamsVersion = "v4"
	GetParamsVersionV7   GetParamsVersion = "v7"
)

Defines values for GetParamsVersion.

type GetResponse added in v0.2.0

type GetResponse struct {
	Body         []byte
	HTTPResponse *http.Response
	JSON200      *struct {
		// contains filtered or unexported fields
	}
	JSON400 *struct {
		Error *string `json:"error,omitempty"`
	}
}

func ParseGetResponse added in v0.2.0

func ParseGetResponse(rsp *http.Response) (*GetResponse, error)

ParseGetResponse parses an HTTP response from a GetWithResponse call

func (GetResponse) Status added in v0.2.0

func (r GetResponse) Status() string

Status returns HTTPResponse.Status

func (GetResponse) StatusCode added in v0.2.0

func (r GetResponse) StatusCode() int

StatusCode returns HTTPResponse.StatusCode

type HttpRequestDoer added in v0.2.0

type HttpRequestDoer interface {
	Do(req *http.Request) (*http.Response, error)
}

Doer performs HTTP requests.

The standard http.Client implements this interface.

type RequestEditorFn added in v0.2.0

type RequestEditorFn func(ctx context.Context, req *http.Request) error

RequestEditorFn is the function signature for the RequestEditor callback function

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