{"id":47603155,"url":"https://github.com/zoobz-io/atom","last_synced_at":"2026-04-01T18:58:42.612Z","repository":{"id":330271170,"uuid":"1119793485","full_name":"zoobz-io/atom","owner":"zoobz-io","description":"Type-segregated atomic value decomposition for Go","archived":false,"fork":false,"pushed_at":"2026-03-19T23:44:40.000Z","size":234,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-20T05:23:17.310Z","etag":null,"topics":["decomposition","go","golang","reflection","struct","type-safety","zoobzio"],"latest_commit_sha":null,"homepage":"https://atom.zoobz.io","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/zoobz-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-19T21:29:55.000Z","updated_at":"2026-03-19T23:36:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zoobz-io/atom","commit_stats":null,"previous_names":["zoobzio/atom","zoobz-io/atom"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/zoobz-io/atom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoobz-io%2Fatom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoobz-io%2Fatom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoobz-io%2Fatom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoobz-io%2Fatom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zoobz-io","download_url":"https://codeload.github.com/zoobz-io/atom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zoobz-io%2Fatom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["decomposition","go","golang","reflection","struct","type-safety","zoobzio"],"created_at":"2026-04-01T18:58:42.529Z","updated_at":"2026-04-01T18:58:42.600Z","avatar_url":"https://github.com/zoobz-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# atom\n\n[![CI Status](https://github.com/zoobz-io/atom/workflows/CI/badge.svg)](https://github.com/zoobz-io/atom/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/zoobz-io/atom/graph/badge.svg?branch=main)](https://codecov.io/gh/zoobz-io/atom)\n[![Go Report Card](https://goreportcard.com/badge/github.com/zoobz-io/atom)](https://goreportcard.com/report/github.com/zoobz-io/atom)\n[![CodeQL](https://github.com/zoobz-io/atom/workflows/CodeQL/badge.svg)](https://github.com/zoobz-io/atom/security/code-scanning)\n[![Go Reference](https://pkg.go.dev/badge/github.com/zoobz-io/atom.svg)](https://pkg.go.dev/github.com/zoobz-io/atom)\n[![License](https://img.shields.io/github/license/zoobz-io/atom)](LICENSE)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/zoobz-io/atom)](go.mod)\n[![Release](https://img.shields.io/github/v/release/zoobz-io/atom)](https://github.com/zoobz-io/atom/releases)\n\nType-segregated struct decomposition for Go.\n\nBreak structs into typed maps, work with fields programmatically, reconstruct later — without knowing T.\n\n## Normalized Type-Safe Data Without the Types\n\nUser code knows its types. Infrastructure code doesn't need to.\n\n```go\n// User side: knows T\ntype User struct {\n    ID      string\n    Name    string\n    Age     int64\n    Balance float64\n    Active  bool\n}\n\natomizer, _ := atom.Use[User]()\nuser := \u0026User{ID: \"usr-1\", Name: \"Alice\", Age: 30, Balance: 100.50, Active: true}\na := atomizer.Atomize(user)\n\n// Pass atom to any library...\nresult := storage.Save(a)            // storage never imports User\nvalidated := validator.Check(a)      // validator never imports User\ntransformed := migrator.Upgrade(a)   // migrator never imports User\n\n// ...get it back\nrestored, _ := atomizer.Deatomize(result)\n```\n\nThe receiving library sees typed maps and metadata — not T:\n\n```go\n// Library side: doesn't know T, doesn't need T\nfunc Save(a *atom.Atom) *atom.Atom {\n    // Spec describes the struct\n    fmt.Println(a.Spec.TypeName) // \"User\"\n\n    // Typed maps hold the values\n    for field, value := range a.Strings {\n        db.SetString(field, value)\n    }\n    for field, value := range a.Ints {\n        db.SetInt(field, value)\n    }\n    for field, value := range a.Floats {\n        db.SetFloat(field, value)\n    }\n\n    return a\n}\n```\n\nType-safe field access. Zero knowledge of the original struct.\n\n## Install\n\n```bash\ngo get github.com/zoobz-io/atom@latest\n```\n\nRequires Go 1.24+.\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/zoobz-io/atom\"\n)\n\ntype Order struct {\n    ID     string\n    Total  float64\n    Status string\n}\n\nfunc main() {\n    // Register the type once\n    atomizer, err := atom.Use[Order]()\n    if err != nil {\n        panic(err)\n    }\n\n    order := \u0026Order{ID: \"order-123\", Total: 99.99, Status: \"pending\"}\n\n    // Decompose to atom\n    a := atomizer.Atomize(order)\n\n    // Work with typed maps\n    fmt.Printf(\"ID: %s\\n\", a.Strings[\"ID\"])\n    fmt.Printf(\"Total: %.2f\\n\", a.Floats[\"Total\"])\n\n    // Modify fields\n    a.Strings[\"Status\"] = \"confirmed\"\n\n    // Reconstruct\n    restored, _ := atomizer.Deatomize(a)\n    fmt.Printf(\"Status: %s\\n\", restored.Status) // \"confirmed\"\n}\n```\n\n## Capabilities\n\n| Feature                | Description                                                       | Docs                                                |\n| ---------------------- | ----------------------------------------------------------------- | --------------------------------------------------- |\n| Type Segregation       | Strings, ints, floats, bools, times, bytes in separate typed maps | [Concepts](docs/2.learn/2.concepts.md)              |\n| Nullable Fields        | Pointer types (`*string`, `*int64`) with explicit nil handling    | [Basic Usage](docs/3.guides/1.basic-usage.md)       |\n| Slices                 | `[]string`, `[]int64`, etc. preserved as typed slices             | [Basic Usage](docs/3.guides/1.basic-usage.md)       |\n| Nested Composition     | Embed atoms within atoms for complex object graphs                | [Nested Structs](docs/3.guides/3.nested-structs.md) |\n| Field Introspection    | Query fields, tables, and type metadata via Spec                  | [API Reference](docs/5.reference/1.api.md)          |\n| Custom Implementations | `Atomizable`/`Deatomizable` interfaces bypass reflection          | [Interfaces](docs/3.guides/4.interfaces.md)         |\n| Code Generation        | Generate implementations for zero-reflection paths                | [Code Generation](docs/4.cookbook/1.codegen.md)     |\n\n## Why atom?\n\n- **Type-safe without T** — Libraries work with typed maps, not `any` or reflection\n- **Field-level control** — Read, write, transform individual fields programmatically\n- **Decoupled** — Infrastructure code never imports user types\n- **Zero reflection path** — Implement interfaces or use codegen for production performance\n- **Sentinel integration** — Automatic field discovery and metadata extraction\n\n## The Typed Bridge\n\nAtom enables a pattern: **user code owns types, infrastructure owns behaviour**.\n\nYour application defines structs. Libraries accept atoms. Each side works with what it knows — concrete types on one end, typed maps on the other. No shared type imports. No reflection at runtime (with codegen).\n\n```go\n// Your domain package defines types\ntype User struct { ... }\ntype Order struct { ... }\n\n// Storage library accepts atoms — never sees User or Order\nfunc (s *Store) Put(a *atom.Atom) error { ... }\nfunc (s *Store) Get(spec atom.Spec, id string) (*atom.Atom, error) { ... }\n\n// Your code bridges the two\na := userAtomizer.Atomize(user)\nstore.Put(a)\n```\n\nThe contract is the Atom structure. The types stay where they belong.\n\n## Documentation\n\n### Learn\n\n- [Quickstart](docs/2.learn/1.quickstart.md) — Get started in 5 minutes\n- [Core Concepts](docs/2.learn/2.concepts.md) — Atoms, tables, specs\n- [Architecture](docs/2.learn/3.architecture.md) — Internal design\n\n### Guides\n\n- [Basic Usage](docs/3.guides/1.basic-usage.md) — Common patterns\n- [Custom Types](docs/3.guides/2.custom-types.md) — Named types and enums\n- [Nested Structs](docs/3.guides/3.nested-structs.md) — Composition\n- [Interfaces](docs/3.guides/4.interfaces.md) — Custom serialization\n- [Testing](docs/3.guides/5.testing.md) — Test strategies\n\n### Cookbook\n\n- [Code Generation](docs/4.cookbook/1.codegen.md) — Eliminating reflection\n- [Serialization](docs/4.cookbook/2.serialization.md) — Encoding atoms\n- [Migrations](docs/4.cookbook/3.migrations.md) — Schema evolution\n\n### Reference\n\n- [API Reference](docs/5.reference/1.api.md) — Complete API\n- [Tables Reference](docs/5.reference/2.tables.md) — All table types\n- [Testing Reference](docs/5.reference/3.testing.md) — Test utilities\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Run `make help` for available commands.\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoobz-io%2Fatom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzoobz-io%2Fatom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzoobz-io%2Fatom/lists"}