init open source commit

.github/workflows/ci.yaml

@@ -0,0 +1,46 @@
+name: Test, Vet, and Coverage
+
+on:
+  push:
+    branches: [ "master" ]
+    tags: [ "v*" ]
+  pull_request:
+    branches: [ "master" ]
+
+env:
+  GITHUB_ORG: ${{ github.repository_owner }}
+
+jobs:
+  lint-vet-build-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version: ['1.22']
+
+    steps:
+    - name: Checkout Code
+      uses: actions/checkout@v4
+
+    - name: Setup Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: ${{ matrix.go-version }}
+
+    - name: Run go mod download
+      run: go mod download
+
+    - name: Lint Go Code
+      uses: golangci/golangci-lint-action@v3
+      with:
+        version: latest
+
+    - name: Run go vet
+      run: make vet
+
+    - name: Run Tests and Generate Coverage
+      run: go test -race -coverprofile=coverage.txt -covermode=atomic ./...
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -0,0 +1,33 @@
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+go.work.sum
+
+# env file
+.env
+
+# darwin system files
+.DS_Store
+
+# devbox files
+.devbox/
+
+# End of https://www.toptal.com/developers/gitignore/api/go

Makefile

@@ -0,0 +1,78 @@
+.PHONY: all
+all: generate
+
+##@ General
+
+# The help target prints out all targets with their descriptions organized
+# beneath their categories. The categories are represented by '##@' and the
+# target descriptions by '##'. The awk command is responsible for reading the
+# entire set of makefiles included in this invocation, looking for lines of the
+# file as xyz: ## something, and then pretty-format the target and help. Then,
+# if there's a line with ##@ something, that gets pretty-printed as a category.
+# More info on the usage of ANSI control characters for terminal formatting:
+# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters
+# More info on the awk command:
+# http://linuxcommand.org/lc3_adv_awk.php
+
+.PHONY: help
+help: ## Display the list of targets and their descriptions
+	@awk 'BEGIN {FS = ":.*##"; printf "\n\033[1mUsage:\033[0m\n  make \033[36m<target>\033[0m\n"} \
+		/^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } \
+		/^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } \
+		/^###/ { printf "  \033[90m%s\033[0m\n", substr($$0, 4) }' $(MAKEFILE_LIST)
+
+##@ Tooling 
+
+.PHONY: install-devbox
+install-devbox: ## Install Devbox
+	@echo "Installing Devbox..."
+	@curl -fsSL https://get.jetify.dev | bash
+
+.PHONY: devbox-update
+devbox-update: ## Update Devbox
+	@devbox update
+
+.PHONY: devbox
+devbox: ## Run Devbox shell
+	@devbox shell
+
+##@ Installation
+
+.PHONY: install
+install: ## Download go modules
+	@echo "Downloading go modules..."
+	go mod download
+
+##@ Development
+
+.PHONY: fmt
+fmt: ## Run go fmt
+	@echo "Running go fmt..."
+	go fmt ./...
+
+.PHONY: generate
+generate: ## Generate and embed go documentation into README.md
+	@echo "Generating and embedding go documentation into README.md..."
+	go generate ./...
+
+.PHONY: vet
+vet: ## Run go vet
+	@echo "Running go vet..."
+	go vet ./...
+
+.PHONY: lint
+lint: ## Run golangci-lint
+	@echo "Running golangci-lint..."
+	golangci-lint run ./...
+
+##@ Testing & Benchmarking
+
+.PHONY: test
+test: ## Run Go tests
+	@echo "Running go tests..."
+	go test ./... -tags=test
+
+.PHONY: bench
+bench: ## Run Go benchmarks
+	@echo "Running go benchmarks..."
+	go test ./... -tags=bench -bench=.

README.md

@@ -0,0 +1,183 @@
+```sh
+                           ____        _     _ _      ___ ____  
+                          |  _ \ _   _| |__ | (_) ___|_ _|  _ \ 
+                          | |_) | | | | '_ \| | |/ __|| || | | |
+                          |  __/| |_| | |_) | | | (__ | || |_| |
+                          |_|    \__,_|_.__/|_|_|\___|___|____/ 
+```
+<!-- [![Sourcegraph](https://sourcegraph.com/github.com/agentstation/publicid/-/badge.svg?style=flat-square)](https://sourcegraph.com/github.com/agentstation/publicid?badge) -->
+[![GoDoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](https://pkg.go.dev/github.com/agentstation/publicid)
+[![Go Report Card](https://goreportcard.com/badge/github.com/agentstation/publicid?style=flat-square)](https://goreportcard.com/report/github.com/agentstation/publicid)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/agentstation/publicid/ci.yaml?style=flat-square)](https://github.com/agentstation/publicid/actions)
+[![codecov](https://codecov.io/gh/agentstation/publicid/branch/master/graph/badge.svg?token=35UM5QX1Q3)](https://codecov.io/gh/agentstation/publicid)
+[![License](http://img.shields.io/badge/license-mit-blue.svg?style=flat-square)](https://raw.githubusercontent.com/agentstation/publicid/master/LICENSE)
+<!-- [![Forum](https://img.shields.io/badge/community-forum-00afd1.svg?style=flat-square)](https://github.com/agentstation/publicid/discussions) -->
+<!-- [![Twitter](https://img.shields.io/badge/twitter-@agentstationHQ-55acee.svg?style=flat-square)](https://twitter.com/agentstationHQ) -->
+
+The `publicid` package generates and validates NanoID strings designed to be publicly exposed.
+
+## Installation
+
+```sh
+go get github.com/agentstation/publicid
+```
+
+## Usage
+
+To use the `publicid` package, you can import it into your Go project and call the `New` or `NewLong` functions to generate a public ID.
+
+```go
+import (
+    "github.com/agentstation/publicid"
+)
+
+id, err := publicid.New()
+if err != nil {
+  log.Fatalf("Failed to generate public ID: %v", err)
+}
+
+fmt.Println("Generated public ID:", id)
+```
+
+The `New` function generates a public ID with a length of 8 characters, while the `NewLong` function generates a public ID with a length of 12 characters.
+
+You can also use the `Attempts` option to specify the number of attempts to generate a unique public ID.
+
+```go
+id, err := publicid.New(publicid.Attempts(5))
+if err != nil {
+  log.Fatalf("Failed to generate public ID: %v", err)
+}
+
+fmt.Println("Generated public ID:", id)
+```
+
+<!-- gomarkdoc:embed:start -->
+
+<!-- Code generated by gomarkdoc. DO NOT EDIT -->
+
+# publicid
+
+```go
+import "github.com/agentstation/publicid"
+```
+
+## Index
+
+- [func New\(opts ...Option\) \(string, error\)](<#New>)
+- [func NewLong\(opts ...Option\) \(string, error\)](<#NewLong>)
+- [func Validate\(id string\) error](<#Validate>)
+- [func ValidateLong\(fieldName, id string\) error](<#ValidateLong>)
+- [type Option](<#Option>)
+  - [func Attempts\(n int\) Option](<#Attempts>)
+
+
+<a name="New"></a>
+## func [New](<https://github.com/agentstation/publicid/blob/main/publicid.go#L31>)
+
+```go
+func New(opts ...Option) (string, error)
+```
+
+New generates a unique nanoID with a length of 8 characters and the given options.
+
+<a name="NewLong"></a>
+## func [NewLong](<https://github.com/agentstation/publicid/blob/main/publicid.go#L36>)
+
+```go
+func NewLong(opts ...Option) (string, error)
+```
+
+NewLong generates a unique nanoID with a length of 12 characters and the given options.
+
+<a name="Validate"></a>
+## func [Validate](<https://github.com/agentstation/publicid/blob/main/publicid.go#L60>)
+
+```go
+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.
+
+<a name="ValidateLong"></a>
+## func [ValidateLong](<https://github.com/agentstation/publicid/blob/main/publicid.go#L66>)
+
+```go
+func ValidateLong(fieldName, id string) error
+```
+
+validateLong checks if a given field name's public ID value is valid according to the constraints defined by package publicid.
+
+<a name="Option"></a>
+## type [Option](<https://github.com/agentstation/publicid/blob/main/publicid.go#L16>)
+
+Option is a function type for configuring ID generation.
+
+```go
+type Option func(*config)
+```
+
+<a name="Attempts"></a>
+### func [Attempts](<https://github.com/agentstation/publicid/blob/main/publicid.go#L24>)
+
+```go
+func Attempts(n int) Option
+```
+
+Attempts returns an Option to set the number of attempts for ID generation.
+
+Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)
+
+
+<!-- gomarkdoc:embed:end -->
+
+## Makefile
+
+```sh
+make help
+
+Usage:
+  make <target>
+
+General
+  help                  Display the list of targets and their descriptions
+
+Tooling
+  install-devbox        Install Devbox
+  devbox-update         Update Devbox
+  devbox                Run Devbox shell
+
+Installation
+  install               Download go modules
+
+Development
+  fmt                   Run go fmt
+  generate              Generate and embed go documentation into README.md
+  vet                   Run go vet
+  lint                  Run golangci-lint
+
+Testing & Benchmarking
+  test                  Run Go tests
+  bench                 Run Go benchmarks
+  ```
+
+## Benchmarks
+
+> **Note:** These benchmarks were run on an Apple M2 Max CPU with 12 cores (8 performance and 4 efficiency) and 32 GB of memory, running macOS 14.6.1.
+
+*Your mileage may vary.*
+
+```sh
+go test -bench=.
+goos: darwin
+goarch: arm64
+pkg: github.com/agentstation/publicid
+BenchmarkNew-12                      2012978           574.8 ns/op
+BenchmarkNewWithAttempts-12          2091734           577.3 ns/op
+BenchmarkLong-12                     1966120           616.9 ns/op
+BenchmarkLongWithAttempts-12         1952052           610.4 ns/op
+BenchmarkValidate-12                100000000            10.73 ns/op
+BenchmarkValidateLong-12            99347000            13.31 ns/op
+PASS
+ok      github.com/agentstation/publicid    9.790s
+```

devbox.json

@@ -0,0 +1,14 @@
+{
+  "packages": [
+    "git@2.44.1",
+    "curl@8.6.0",
+    "go@1.22.5",
+    "golangci-lint@1.60.3",
+    "gomarkdoc@1.1.0"
+  ],
+  "shell": {
+    "init_hook": [
+      "PS1=\"$(echo -e \"\\033[1;34m%~\\033[0m \\n\\033[0;32m%n@devbox\\033[0m ➜ \")\""
+    ]
+  }
+}