{"id":51596917,"url":"https://github.com/crystallabs/superconf.cr","last_synced_at":"2026-07-11T19:30:41.023Z","repository":{"id":367320133,"uuid":"1275991986","full_name":"crystallabs/superconf.cr","owner":"crystallabs","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-25T12:41:54.000Z","size":34,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-25T14:17:05.664Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Crystal","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crystallabs.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-21T12:03:12.000Z","updated_at":"2026-06-25T12:41:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/crystallabs/superconf.cr","commit_stats":null,"previous_names":["crystallabs/superconf.cr"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/crystallabs/superconf.cr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystallabs%2Fsuperconf.cr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystallabs%2Fsuperconf.cr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystallabs%2Fsuperconf.cr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystallabs%2Fsuperconf.cr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crystallabs","download_url":"https://codeload.github.com/crystallabs/superconf.cr/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crystallabs%2Fsuperconf.cr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35374165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-07-11T19:30:40.443Z","updated_at":"2026-07-11T19:30:41.018Z","avatar_url":"https://github.com/crystallabs.png","language":"Crystal","funding_links":[],"categories":[],"sub_categories":[],"readme":"# superconf\n\nA small, framework-agnostic, process-wide **configuration registry** for Crystal.\n\nEvery tunable — in a library *or* the app using it — is registered once and\nbecomes reachable from four synchronized surfaces, each value carrying the\n**source** it came from:\n\n| Surface | Form (key `screen.resize_interval`) |\n|---|---|\n| Config key | `screen.resize_interval` (YAML/JSON) |\n| Environment variable | `\u003cPREFIX\u003eSCREEN_RESIZE_INTERVAL` |\n| Command-line option | `--screen-resize-interval` |\n| Runtime | `Superconf.screen_resize_interval` (typed accessor) |\n\nBecause the registry is a single process-wide singleton, several independent\ncomponents that all register into it — e.g. a terminal library and the\napplication built on top of it — appear together in **one combined, dumpable\nlist**.\n\n## Quick start\n\n```crystal\nrequire \"superconf\"\n\nmodule Superconf\n  option \"myapp.refresh\", 1.second, description: \"Refresh interval\"\n  option \"myapp.workers\", 4, validate: -\u003e(n : Int32) { n \u003e 0 }\nend\n\nSuperconf.app_name   = \"myapp\"      # ~/.config/myapp/config.yml\nSuperconf.env_prefix = \"MYAPP_\"     # MYAPP_MYAPP_REFRESH, ...\n\nSuperconf.configure!                # file (if present) + env + CLI, in precedence order\n\nSuperconf.myapp_refresh             # =\u003e Time::Span (typed, cached read)\nSuperconf.myapp_refresh = 5.seconds\n```\n\nPrecedence, low → high: **default \u003c config file \u003c env var \u003c command-line \u003c\nruntime assignment**.\n\n## Declaring options\n\n`option key, default, …` infers the value type from `default`. Built-in parsing\ncovers `Bool`, `Int32`, `Int64`, `Float64`, `String`, `Char`, `Time::Span`, and\nany `Enum` (including `@[Flags]`). For other types pass a `parse:` proc. Add a\n`validate:` predicate to reject out-of-range values from any source.\n\n`register` is the same thing without the typed accessor (for keys known only at\nruntime). `get(key, T)` / `set(key, v)` are the dynamic, string-keyed API used\nby the loaders.\n\n## Overriding and aliasing lower-level options\n\nA library registers an option; the app on top can adjust it without touching the\nlibrary. Two ways:\n\n* **`set_default key, value`** — change the *baseline* while keeping it\n  overridable (a config file / env var / CLI flag / runtime assignment still\n  wins). Use it when the app wants a different default than the library's.\n\n* **`register_alias alias_key, target_key`** (or the typed `option_alias` macro)\n  — *promote* an option under a second name. The alias shares the one value,\n  type, default, parsing and validation, but gains its own config key, env var\n  and CLI flag. Reading or writing either name affects the same value.\n\n```crystal\nmodule Superconf\n  option \"screen.resize_interval\", 0.2.seconds   # declared by a library\n\n  # The app considers this important enough to surface under its own name:\n  option_alias \"myapp.refresh\", \"screen.resize_interval\", Time::Span\nend\n\nSuperconf.myapp_refresh = 1.second                # writes the shared value\nSuperconf.screen_resize_interval                  # =\u003e 1.second\n# MYAPP_REFRESH / --myapp-refresh / `myapp.refresh:` now work too\n```\n\nAliasing an alias resolves to the same underlying option. Aliases stay out of\nthe re-loadable value dumps (the canonical name already carries the value) but\nappear in the `report` dump with an `alias_of` field.\n\n## Dumping\n\n`Superconf.dump(io, format)` (or `--dump-config[ FORMAT]` once `configure!` /\n`load_args` runs) emits:\n\n* `yaml` (default) and `json` — valid, **re-loadable** config files;\n* `env` — a sourceable `export …='value'` script;\n* `pretty` — an aligned table showing each value's **source**;\n* `report` — rich JSON with full per-option metadata.\n\n## Errors\n\nA single `Superconf::Error` covers unknown keys, type mismatches, unparseable\nvalues, and failed validation — `rescue Superconf::Error` to handle all of them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrystallabs%2Fsuperconf.cr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrystallabs%2Fsuperconf.cr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrystallabs%2Fsuperconf.cr/lists"}