{"id":51130129,"url":"https://github.com/williamwutq/mappedvartrie","last_synced_at":"2026-06-25T11:30:48.455Z","repository":{"id":352322943,"uuid":"1211361994","full_name":"williamwutq/mappedvartrie","owner":"williamwutq","description":"A persistent, memory-mapped trie for Rust where keys are sequences of variable-length byte segments.","archived":false,"fork":false,"pushed_at":"2026-04-19T00:33:32.000Z","size":51,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-19T02:39:08.050Z","etag":null,"topics":["data-structure","data-structures","database","memory-mapped","mmap","tree","trie"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/williamwutq.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-04-15T10:12:32.000Z","updated_at":"2026-04-19T00:33:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/williamwutq/mappedvartrie","commit_stats":null,"previous_names":["williamwutq/mappedvartrie"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/williamwutq/mappedvartrie","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamwutq%2Fmappedvartrie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamwutq%2Fmappedvartrie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamwutq%2Fmappedvartrie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamwutq%2Fmappedvartrie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/williamwutq","download_url":"https://codeload.github.com/williamwutq/mappedvartrie/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamwutq%2Fmappedvartrie/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34773841,"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-06-25T02:00:05.521Z","response_time":101,"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":["data-structure","data-structures","database","memory-mapped","mmap","tree","trie"],"created_at":"2026-06-25T11:30:47.731Z","updated_at":"2026-06-25T11:30:48.450Z","avatar_url":"https://github.com/williamwutq.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mappedvartrie\n\nA persistent, memory-mapped trie for Rust where keys are sequences of variable-length byte segments.\n\nBuilt by Claude.\n\n## Features\n\n- File-backed storage via `mmap` — data survives process restarts\n- Crash-safe writes with a write-ahead log (WAL) fsynced before every `insert` or `delete`;\n  an interrupted write is automatically replayed on next open, leaving the trie consistent\n- Corruption detection — every node page carries a CRC32 checksum; a partial write is\n  detected immediately and reported as an error\n- Thread-safe: all public methods take `\u0026self` and can be shared via `Arc`\n- Overflow linked list — nodes that exceed `MAX_CHILDREN` (15) children automatically\n  chain overflow pages rather than failing\n- Empty-node GC list — nodes emptied by `delete` are recycled before new pages are\n  allocated, keeping file growth minimal\n- Generic `TrieKey` trait for typed keys alongside the raw `\u0026[\u0026[u8]]` API\n- Prefix scan — retrieve all entries whose key begins with a given prefix\n\n## Constraints\n\nKeys are sequences of byte slices (`\u0026[\u0026[u8]]`), where each segment can be up to 256 bytes.\nValues are arbitrary byte slices up to 65535 bytes. Both keys and values are heap-allocated\non read — there is no zero-copy borrow from the mmap.\n\n## On-disk format\n\nThree files are associated with a database path `{db}`:\n\n| File        | Contents                                      |\n|-------------|-----------------------------------------------|\n| `{db}`      | Node pages (page 0 = file header, 1 = root, …) |\n| `{db}.vals` | Value heap (append-only, offset-addressed)    |\n| `{db}.wal`  | Write-ahead log (present only mid-operation)  |\n\nEach 4096-byte page holds a 32-byte header and up to 15 child slots of 266 bytes each\n(2-byte segment length + 256-byte segment bytes + 8-byte child-page pointer).\n\n## Quick start\n\n```toml\n[dependencies]\nmappedvartrie = \"0.1\"\n```\n\n```rust\nuse mappedvartrie::MappedVarTrie;\n\nlet trie = MappedVarTrie::open(\"data.db\")?;\n\n// Raw \u0026[\u0026[u8]] API — segments are the path through the trie.\ntrie.insert(\u0026[b\"usr\", b\"local\", b\"bin\"], b\"exec\")?;\ntrie.insert(\u0026[b\"usr\", b\"local\", b\"lib\"], b\"libs\")?;\ntrie.insert(\u0026[b\"usr\", b\"share\"], b\"share\")?;\n\nassert_eq!(trie.get(\u0026[b\"usr\", b\"local\", b\"bin\"])?, Some(b\"exec\".to_vec()));\nassert!(trie.contains_key(\u0026[b\"usr\", b\"share\"])?);\n\n// Prefix scan — returns all (key_segments, value) pairs under a prefix.\nlet entries = trie.prefix_scan(\u0026[b\"usr\", b\"local\"])?;\nassert_eq!(entries.len(), 2);\n\ntrie.delete(\u0026[b\"usr\", b\"share\"])?;\nassert_eq!(trie.len()?, 2);\n```\n\n## Generic `TrieKey` API\n\nImplement `TrieKey` for any type that can be decomposed into byte segments:\n\n```rust\nuse mappedvartrie::TrieKey;\n\nstruct PathKey(String);\n\nimpl TrieKey for PathKey {\n    type Segment = Vec\u003cu8\u003e;\n    type SegmentIter\u003c'a\u003e = std::iter::Map\u003cstd::str::Split\u003c'a, char\u003e, fn(\u0026str) -\u003e Vec\u003cu8\u003e\u003e;\n\n    fn segments(\u0026self) -\u003e Self::SegmentIter\u003c'_\u003e {\n        self.0.split('/').map(|s| s.as_bytes().to_vec())\n    }\n}\n\nlet key = PathKey(\"usr/local/bin\".into());\ntrie.insert_key(\u0026key, b\"exec\")?;\nassert_eq!(trie.get_key(\u0026key)?, Some(b\"exec\".to_vec()));\ntrie.delete_key(\u0026key)?;\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamwutq%2Fmappedvartrie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilliamwutq%2Fmappedvartrie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamwutq%2Fmappedvartrie/lists"}