{"id":15293270,"url":"https://github.com/lucmq/go-shelve","last_synced_at":"2025-05-07T04:03:31.821Z","repository":{"id":243896295,"uuid":"813629331","full_name":"lucmq/go-shelve","owner":"lucmq","description":"A persistent, map-like object for the Go programming language. Supports customization.","archived":false,"fork":false,"pushed_at":"2025-04-16T22:09:53.000Z","size":161,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-07T04:03:21.149Z","etag":null,"topics":["database","go","golang","key-value","shelve"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucmq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-11T12:47:32.000Z","updated_at":"2025-04-17T12:58:24.000Z","dependencies_parsed_at":"2025-04-16T23:33:03.450Z","dependency_job_id":"e5d057a2-2084-414d-b141-46a9f59afd52","html_url":"https://github.com/lucmq/go-shelve","commit_stats":null,"previous_names":["lucmq/go-shelve"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucmq%2Fgo-shelve","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucmq%2Fgo-shelve/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucmq%2Fgo-shelve/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucmq%2Fgo-shelve/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucmq","download_url":"https://codeload.github.com/lucmq/go-shelve/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252810271,"owners_count":21807759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","go","golang","key-value","shelve"],"created_at":"2024-09-30T16:45:19.290Z","updated_at":"2025-05-07T04:03:31.784Z","avatar_url":"https://github.com/lucmq.png","language":"Go","funding_links":[],"categories":["Data Structures and Algorithms","Data Integration Frameworks","数据结构与算法"],"sub_categories":["Maps","地图"],"readme":"# Go-Shelve\n[![Go Reference](https://pkg.go.dev/badge/github.com/lucmq/go-shelve/shelve.svg)](https://pkg.go.dev/github.com/lucmq/go-shelve/shelve)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)\n[![Go Report Card](https://goreportcard.com/badge/github.com/lucmq/go-shelve)](https://goreportcard.com/report/github.com/lucmq/go-shelve)\n[![Go Coverage](https://github.com/lucmq/go-shelve/wiki/coverage.svg)](https://raw.githack.com/wiki/lucmq/go-shelve/coverage.html)\n[![DeepSource](https://app.deepsource.com/gh/lucmq/go-shelve.svg/?label=active+issues\u0026show_trend=false\u0026token=iZaN7kSfuZGm1KppBKaqMHME)](https://app.deepsource.com/gh/lucmq/go-shelve/)\n\nGo-Shelve is a dependencies-free Go package that provides a persistent, map-like\nobject called `Shelf`. It lets you store and retrieve Go objects directly, with\nthe serialization and storage handled automatically by the `Shelf`. Additionally,\nyou can customize the underlying key-value storage and serialization Codec to\nbetter suit your application's needs.\n\nThis project is inspired by the `shelve` module from the Python standard\nlibrary and aims to provide a similar set of functionalities.\n\nCheck the [driver's directory](./driver/README.md) for additional storage and\nCodec options.\n\n## Installation\nTo use this package in your Go project, you can install it using `go get`:\n```bash\ngo get github.com/lucmq/go-shelve\n```\n\n## Usage\nHere are some examples of how to use `go-shelve`:\n\n### Basic\nThe following example illustrates the usage of a `Shelf` with string keys and\nvalues. The `Shelf` type uses generics and can be instantiated with any Go type\nas a value and any comparable type for the key.\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\t\"path/filepath\"\n\n\t\"github.com/lucmq/go-shelve/shelve\"\n)\n\nfunc main() {\n\t// Note: In a real application be sure to replace the\n\t// os.TempDir() with a non temporary directory and\n\t// provide better error treatment. \n\tpath := filepath.Join(os.TempDir(), \"go-shelve\")\n\n\t// Open the shelf with default options\n\tshelf, err := shelve.Open[string, string](path)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer shelf.Close()\n\n\t// Use the database\n\tshelf.Put(\"language\", \"Go\")\n\tshelf.Put(\"module\", \"Go-Shelve\")\n\n\t// Note: Saved values will be available between restarts\n\tvalue, ok, _ := shelf.Get(\"language\")\n\tfmt.Println(value, ok)\n\t\n\t// Output: Go true\n}\n```\n\n### Custom Database and Codec\nBy default, a `Shelf` serializes data using the Gob format and stores it using\n`sdb` (for \"shelve-db\"), a simple key-value storage created for this project.\n\nThis database should be suitable for a wide range of applications, but the\n[driver's directory](./driver/README.md) provides additional options for\nconfiguring a `Shelf` with other databases from the Go ecosystem.\n\nThe example below shows how to customize a `Shelf` to use `BoltDB` for storage\ntogether with `MessagePack` for serialization:\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"log\"\n\t\"os\"\n\t\"path/filepath\"\n\n\tbboltd \"github.com/lucmq/go-shelve/driver/db/bbolt\"\n\t\"github.com/lucmq/go-shelve/driver/encoding/msgpack\"\n\t\"github.com/lucmq/go-shelve/shelve\"\n)\n\nfunc main() {\n\tpath := filepath.Join(os.TempDir(), \"bolt-example\")\n\n\tdb, _ := bboltd.NewDefault(path, []byte(\"example-bucket\"))\n\tcodec := msgpack.NewDefault()\n\n\t// Open the shelf with custom options\n\tshelf, err := shelve.Open[string, string](\n\t\tpath,\n\t\tshelve.WithDatabase(db),\n\t\tshelve.WithCodec(codec),\n\t)\n\tif err != nil {\n\t\tlog.Fatal(err)\n\t}\n\tdefer shelf.Close()\n\n\t// Use the database\n\tshelf.Put(\"language\", \"Go\")\n\tshelf.Put(\"module\", \"Go-Shelve\")\n\n\tvalue, ok, _ := shelf.Get(\"language\")\n\tfmt.Println(value, ok)\n\n\t// Output: Go true\n}\n```\n\n### Readable files with `diskv` and `JSON`\nAn interesting use case for `Shelf` is storing data in files that can be read\ntransparently with the `JSON` format, each named by a semantically meaningful\nkey. This can be used to save configuration and application data as\nhuman-readable files.\n\nThe `diskv` driver in [`driver/db/diskv`](./driver/db/diskv) provides a\ndatabase driver that uses a key-value store based on a file-per-record design\nthat would suit this purpose.\n\nThe example below provides a simple illustration of how this could be done to\nsave data for an imaginary game:\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"path/filepath\"\n\n\tdiskvd \"github.com/lucmq/go-shelve/driver/db/diskv\"\n\t\"github.com/lucmq/go-shelve/shelve\"\n)\n\nvar StoragePath = filepath.Join(os.TempDir(), \"game-test\", \"db\")\n\ntype Player struct {\n\tName  string\n\tLevel int\n\tGold  int\n\tItems []string\n}\n\ntype Config struct {\n\tDifficulty string\n}\n\n// NewShelf creates a customized Shelf using Diskv and JSON.\nfunc NewShelf[V any](path string) (*shelve.Shelf[string, V], error) {\n\tpath = filepath.Join(StoragePath, path)\n\textension := \"json\" // Extension of the record files\n\n\tdb, err := diskvd.NewDefault(path, extension)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn shelve.Open[string, V](\n\t\tpath,\n\t\tshelve.WithDatabase(db),\n\t\tshelve.WithCodec(shelve.JSONCodec()),\n\t)\n}\n\nfunc main() {\n\t// Open the shelf with custom options\n\tplayers, _ := NewShelf[Player](\"players\")\n\tconfig, _ := NewShelf[Config](\"config\")\n\n\tdefer players.Close()\n\tdefer config.Close()\n\n\t// Create the game data\n\tplayer := Player{\n\t\tName:  \"Frodo\",\n\t\tLevel: 14,\n\t\tGold:  9999,\n\t\tItems: []string{\"Sting\", \"Lembas\"},\n\t}\n\tcfg := Config{\n\t\tDifficulty: \"Hard\",\n\t}\n\n\t// Save the data. Serialization and persistence will be\n\t// handled automatically by the Shelf.\n\tplayers.Put(player.Name, player)\n\tconfig.Put(\"config\", cfg)\n\n\t// The app storage will contain readable JSON files with\n\t// configuration and game state, that can be retrieved\n\t// back to a Go type:\n\tvalue, ok, _ := players.Get(\"Frodo\")\n\tfmt.Println(ok, value.Name, value.Items)\n\n\t// Output: true Frodo [Sting Lembas]\n}\n```\n\n# Contributing\nContributions to this package are welcome! If you find any issues or have suggestions\nfor improvements, please feel free to open an issue or submit a pull request.\n\nIn particular, if you are interested in contributing a driver for a key-value storage\nor a encoding format, check this [guideline and wishlist](./driver/README.md).\n\n# License\nThis project is licensed under the MIT License - see the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucmq%2Fgo-shelve","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucmq%2Fgo-shelve","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucmq%2Fgo-shelve/lists"}