feat: first implementation

.github/codeql/codeql-config.yml

@@ -0,0 +1,5 @@
+name: CodeQL config
+
+paths-ignore:
+  - mocks
+  - testdata

.github/copilot-instructions.md

@@ -0,0 +1,63 @@
+# Development Guidelines
+
+This document contains the critical information about working with the project codebase.
+Follow these guidelines precisely to ensure consistency and maintainability of the code.
+
+## Stack
+
+- Language: Go (Go 1.26.3)
+- Framework: Go standard library
+- Testing: Go's built-in testing package
+- Dependency Management: Go modules
+- Version Control: Git
+- Documentation: go doc
+- Code Review: Pull requests on GitHub
+- CI/CD: GitHub Actions
+
+## Project Structure
+
+Since this is a small Go library, files are organized in the root directory following standard Go package layout.
+
+- Library files are located in the root directory.
+- `.github/` contains GitHub-specific files such as workflows for CI/CD.
+- `.gitignore` specifies files and directories to be ignored by Git.
+- `LICENSE` is the license file for the project.
+- `README.md` provides an overview of the project, installation instructions, usage examples, and other relevant information.
+- `go.mod` declares the module and Go toolchain version.
+- `go.sum` should not exist unless external dependencies are intentionally introduced.
+- `*.go` files contain the main source code of the library.
+- `*_test.go` files contain tests, benchmarks, and executable examples.
+
+## Code Style
+
+- Follow Go's idiomatic style defined in
+  - <https://google.github.io/styleguide/go/guide>
+  - <https://google.github.io/styleguide/go/decisions>
+  - <https://google.github.io/styleguide/go/best-practices>
+  - <https://golang.org/doc/effective_go.html>
+- Keep package names short, lowercase, and non-stuttering.
+- Use meaningful names for variables, functions, and packages.
+- Keep functions small and focused on a single task.
+- Add comments for exported identifiers and complex behavior.
+- Do not use `interface{}`; use `any` when an unconstrained type is required.
+- Do not add external module dependencies without explicit approval.
+
+## Go 1.26 Practices
+
+- Prefer `errors.AsType[T](err)` over `errors.As(err, &target)` in new code.
+- Use `new(value)` when allocating and initializing pointer values.
+- Use `for b.Loop()` in benchmarks.
+- Run `go fix ./...` after larger changes to apply available modernizations.
+
+## Post-Change Checklist
+
+Use standard Go commands after making changes:
+
+```bash
+go fix ./...
+go fmt ./...
+go vet ./...
+betteralign -apply ./...
+go test -race -coverprofile=/tmp/fsx-coverage.txt -covermode=atomic ./...
+go build ./...
+```

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: gomod
+    directory: /
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

.github/release.yml

@@ -0,0 +1,16 @@
+changelog:
+  categories:
+    - title: Breaking Changes
+      labels:
+        - Semver-Major
+        - breaking-change
+    - title: New Features
+      labels:
+        - Semver-Minor
+        - enhancement
+    - title: Security
+      labels:
+        - security
+    - title: Other Changes
+      labels:
+        - "*"

.github/workflows/codeql.yml

@@ -0,0 +1,44 @@
+name: CodeQL Advanced
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: "10 12 * * 3"
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      packages: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - language: actions
+            build-mode: none
+          - language: go
+            build-mode: autobuild
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: ${{ matrix.build-mode }}
+          config-file: ./.github/codeql/codeql-config.yml
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4
+        with:
+          category: /language:${{ matrix.language }}

.github/workflows/main.yml

@@ -0,0 +1,81 @@
+name: Main
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: ./go.mod
+          cache: true
+
+      - name: Summary Information
+        run: |
+          echo "# Push Summary" > "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Repository:** ${{ github.repository }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Push:** ${{ github.event.head_commit.message }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Author:** ${{ github.event.head_commit.author.name }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Branch:** ${{ github.ref }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Tools and versions
+        run: |
+          echo "## Tools and versions" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Ubuntu Version:** $(lsb_release -ds)" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Bash Version:** $(bash --version | head -n 1 | awk '{print $4}')" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Git Version:** $(git --version | awk '{print $3}')" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Go Version:** $(go version | awk '{print $3}')" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Format check
+        run: |
+          echo "## Format check" >> "$GITHUB_STEP_SUMMARY"
+          files=$(gofmt -l .)
+          if [ -n "$files" ]; then
+            echo "$files"
+            echo "The files above need gofmt." >> "$GITHUB_STEP_SUMMARY"
+            exit 1
+          fi
+          echo "All Go files are gofmt-formatted." >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Vet
+        run: |
+          echo "## Vet" >> "$GITHUB_STEP_SUMMARY"
+          go vet ./... | tee -a "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Test
+        run: |
+          echo "## Test report" >> "$GITHUB_STEP_SUMMARY"
+          go test -race -coverprofile=coverage.txt -covermode=atomic ./... | tee -a "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Test coverage
+        run: |
+          echo "## Test coverage" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          go tool cover -func=coverage.txt | tee -a "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          total_coverage=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}')
+          echo "**Total Coverage:** $total_coverage" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Build
+        run: |
+          echo "## Build" >> "$GITHUB_STEP_SUMMARY"
+          go build ./... | tee -a "$GITHUB_STEP_SUMMARY"
+          echo "Build completed successfully." >> "$GITHUB_STEP_SUMMARY"

.github/workflows/pr.yml

@@ -0,0 +1,58 @@
+name: Pull Request
+
+on:
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: ./go.mod
+          cache: true
+
+      - name: Summary Information
+        run: |
+          echo "# Pull Request Summary" > "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Repository:** ${{ github.repository }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Pull Request:** ${{ github.event.pull_request.title }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Author:** ${{ github.event.pull_request.user.login }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Branch:** ${{ github.event.pull_request.head.ref }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Base:** ${{ github.event.pull_request.base.ref }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Commits:** ${{ github.event.pull_request.commits }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Changed Files:** ${{ github.event.pull_request.changed_files }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Additions:** ${{ github.event.pull_request.additions }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Deletions:** ${{ github.event.pull_request.deletions }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Format check
+        run: |
+          files=$(gofmt -l .)
+          if [ -n "$files" ]; then
+            echo "$files"
+            exit 1
+          fi
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test -race -coverprofile=coverage.txt -covermode=atomic ./...
+
+      - name: Test coverage
+        run: go tool cover -func=coverage.txt
+
+      - name: Build
+        run: go build ./...

.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  actions: write
+  contents: write
+  id-token: write
+  packages: write
+  pull-requests: read
+  security-events: write
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: ./go.mod
+          cache: true
+
+      - name: Summary Information
+        run: |
+          echo "# Release Summary" > "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Repository:** ${{ github.repository }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Actor:** ${{ github.triggering_actor }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Commit ID:** ${{ github.sha }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "**Tag:** ${{ github.ref_name }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Format check
+        run: |
+          files=$(gofmt -l .)
+          if [ -n "$files" ]; then
+            echo "$files"
+            exit 1
+          fi
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Test
+        run: go test -race -coverprofile=coverage.txt -covermode=atomic ./...
+
+      - name: Test coverage
+        run: |
+          echo "## Test coverage" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          go tool cover -func=coverage.txt | tee -a "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          draft: false
+          prerelease: false
+          generate_release_notes: true
+          make_latest: true

.golangci.yaml

@@ -0,0 +1,21 @@
+version: "2"
+linters:
+  enable:
+    - errcheck
+    - ineffassign
+    - staticcheck
+    - unused
+
+  settings:
+    errcheck:
+      check-type-assertions: false
+      check-blank: false
+      disable-default-exclusions: true
+      exclude-functions:
+        - (*os.File).Close
+        - (io.Closer).Close
+        - fmt.Print
+        - fmt.Printf
+        - fmt.Println
+        - fmt.Fprint
+        - fmt.Fprintf