jsonfile

README

jsonfile

Small Go helpers for atomic JSON file read/write and typed on-disk collections.

Install

From pkg.go.dev:

go get github.com/brandonkramer/jsonfile

Quick start

type Config struct {
    Name string `json:"name"`
}

cfg, err := jsonfile.Read[Config]("/etc/myapp/config.json")
if err != nil {
    return err
}

cfg, err = jsonfile.ReadStrict[Config]("/etc/myapp/config.json")
if err != nil {
    return err
}

if err := jsonfile.Write("/etc/myapp/config.json", cfg); err != nil {
    return err
}

Development

Lefthook and golangci-lint are pinned in go.mod as tools (dev-only). Install git hooks once per clone:

make install-hooks

Hooks and make lint use go tool binaries from go.mod. Pre-commit lints staged .go files; pre-push runs ./scripts/check.sh. Skip hooks with LEFTHOOK=0 git push.

make check
make test
make lint

Releases

Tagged semver releases are published to pkg.go.dev. See GitHub releases for notes.

License

MIT

Documentation

Overview

Package jsonfile reads and writes JSON files atomically and provides typed directory collections for on-disk document stores.

Use ReadStrict when decoding config or state files where unknown JSON fields should fail fast. All reads reject trailing content after the first value.

Index

• Constants
• func CapList[T any](items []T, limit int) []T
• func EntryDirName(e os.DirEntry) (string, bool)
• func ListDir[T any](dir string, match EntryMatch, load func(id string) (T, error), ...) ([]T, error)
• func Read[T any](path string) (T, error)
• func ReadStrict[T any](path string) (T, error)
• func Write(path string, v any) error
• func WriteAtomic(path string, data []byte, perm os.FileMode) (err error)
• type Collection
  • func (c Collection[T]) List(root string, keep func(T) bool, limit int) ([]T, error)
  • func (c Collection[T]) Load(root, id string) (T, error)
  • func (c Collection[T]) Save(root string, doc T) error
• type EntryMatch
  • func EntryFileSuffix(suffix string) EntryMatch

Constants

const DefaultFilePerm = 0o644

DefaultFilePerm is the mode used for persisted JSON documents.

Functions

func CapList

func CapList[T any](items []T, limit int) []T

CapList returns at most limit items when limit is positive.

func EntryDirName

func EntryDirName(e os.DirEntry) (string, bool)

EntryDirName matches subdirectories and uses the directory name as id.

func ListDir

func ListDir[T any](dir string, match EntryMatch, load func(id string) (T, error), keep func(T) bool) ([]T, error)

ListDir loads documents from dir using match and load.

func Read

func Read[T any](path string) (T, error)

Read decodes one JSON document from path.

func ReadStrict

func ReadStrict[T any](path string) (T, error)

ReadStrict decodes one JSON document and rejects unknown object fields.

func Write

func Write(path string, v any) error

Write encodes v as indented JSON and atomically replaces path.

func WriteAtomic

func WriteAtomic(path string, data []byte, perm os.FileMode) (err error)

WriteAtomic writes data to path via a temp file and rename.

Types

type Collection

type Collection[T any] struct {
	Dir   func(root string) string
	Match EntryMatch
	Path  func(root, id string) (string, error)
	ID    func(T) string
	Less  func(a, b T) bool
}

Collection persists typed JSON documents under a root directory.

func (Collection[T]) List

func (c Collection[T]) List(root string, keep func(T) bool, limit int) ([]T, error)

List returns documents under root, optionally filtered and capped.

func (Collection[T]) Load

func (c Collection[T]) Load(root, id string) (T, error)

Load reads one document by id from root.

func (Collection[T]) Save

func (c Collection[T]) Save(root string, doc T) error

Save writes doc to its configured path under root.

type EntryMatch

type EntryMatch func(os.DirEntry) (id string, ok bool)

EntryMatch selects directory entries and returns an id for loading.

func EntryFileSuffix

func EntryFileSuffix(suffix string) EntryMatch

EntryFileSuffix matches regular files with the given suffix.