{"id":51317574,"url":"https://github.com/arc-language/arc-versioning","last_synced_at":"2026-07-01T09:01:13.971Z","repository":{"id":361800869,"uuid":"1255869972","full_name":"arc-language/arc-versioning","owner":"arc-language","description":"Automatic model versioning and history for Arc — every mutation snapshotted, one-click revert","archived":false,"fork":false,"pushed_at":"2026-06-01T10:11:45.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T11:16:00.098Z","etag":null,"topics":["arc","audit-log","bun","cms","history","nodejs","revert","sqlite","typescript","versioning"],"latest_commit_sha":null,"homepage":"https://arc-lang.com/docs/versioning","language":"JavaScript","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/arc-language.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"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":"2026-06-01T08:46:10.000Z","updated_at":"2026-06-01T10:11:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arc-language/arc-versioning","commit_stats":null,"previous_names":["arc-language/arc-versioning"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/arc-language/arc-versioning","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arc-language%2Farc-versioning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arc-language%2Farc-versioning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arc-language%2Farc-versioning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arc-language%2Farc-versioning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arc-language","download_url":"https://codeload.github.com/arc-language/arc-versioning/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arc-language%2Farc-versioning/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34999792,"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-01T02:00:05.325Z","response_time":130,"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":["arc","audit-log","bun","cms","history","nodejs","revert","sqlite","typescript","versioning"],"created_at":"2026-07-01T09:01:13.045Z","updated_at":"2026-07-01T09:01:13.945Z","avatar_url":"https://github.com/arc-language.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# arc-versioning\n\n[![npm](https://img.shields.io/npm/v/arc-versioning.svg)](https://www.npmjs.com/package/arc-versioning)\n[![CI](https://github.com/arc-language/arc-versioning/actions/workflows/ci.yml/badge.svg)](https://github.com/arc-language/arc-versioning/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node \u003e=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)\n\n**Automatic model versioning and history for [Arc](https://arc-lang.com).** Every mutation is snapshotted with zero annotation — no decorators, no model changes. Editors can browse the full change history and revert to any previous state with one click.\n\nInspired by [django-reversion](https://github.com/etianen/django-reversion) and [django-simple-history](https://github.com/treyhunner/django-simple-history).\n\n---\n\n## Why\n\nArc has no built-in change history. If an editor overwrites a page or deletes a record, it's gone. `arc-versioning` fixes this by wrapping every database mutation at the framework level — you don't annotate models, you don't change any code. Install the package, add one line to `arc.config.json`, and every future mutation is automatically snapshotted.\n\n---\n\n## Installation\n\n```bash\nnpm install arc-versioning\n```\n\nAdd to `arc.config.json`:\n\n```json\n{ \"packages\": [\"arc-versioning\"] }\n```\n\nDone. Run `arc serve` or `arc build` — every model is now versioned.\n\n---\n\n## Configuration\n\nAll options are optional:\n\n```json\n{\n  \"packages\": [\"arc-versioning\"],\n  \"versioning\": {\n    \"maxVersionsPerRecord\": 100,\n    \"excludeModels\": []\n  }\n}\n```\n\n| Option | Default | Description |\n|---|---|---|\n| `maxVersionsPerRecord` | `100` | Max snapshots per record. Older ones trimmed asynchronously. |\n| `excludeModels` | `[]` | Table names to exclude from versioning. |\n\n---\n\n## How it works\n\nAt build time, `arc-versioning` injects a thin wrapper around every `db.*` model helper:\n\n- **`create`** — snapshots the newly created record (after-state)\n- **`update`** — snapshots the record after update (after-state)\n- **`delete`** — snapshots the record **before** deletion (before-state, so it can be restored)\n\nSnapshots go into a single `_arc_versions` table with three covering indexes for O(log N) access. The wrapper is a ~50-line IIFE emitted into `dist/server.js` — zero runtime dependencies.\n\nFailures are caught and logged as `console.warn` — a broken versioning table will never crash your application.\n\n---\n\n## History viewer (arc-cms)\n\nWhen used with [arc-cms](https://github.com/arc-language/arc-cms), a full history UI is available at:\n\n```\n/admin/history/:model/:id\n```\n\nFeatures:\n- Timeline of all changes, newest first, paginated (20/page)\n- Color-coded action badges — `create` (green), `update` (blue), `delete` (red), `revert` (purple)\n- User attribution (who made the change)\n- Expandable field diffs — shows exactly which fields changed and their before/after values\n- One-click revert with confirmation modal\n- Reverting adds a `revert` entry to the history — the audit trail is never destroyed\n\n---\n\n## REST API\n\nThree routes are automatically registered at `/admin/api`:\n\n```\nGET  /admin/api/versions/:model/:id\n     → { versions[], hasMore, page, total }\n     Paginated history. ?page=N for subsequent pages.\n     User display names are joined automatically.\n\nGET  /admin/api/versions/:model/:id/:versionId\n     → { version, diff[] }\n     Single version with a computed field diff vs. the previous snapshot.\n\nPOST /admin/api/versions/:model/:id/revert/:versionId\n     → { ok: true, revertedToVersionId }\n     Revert to a snapshot. Creates a new `revert` history entry.\n```\n\nAll routes require `admin` or `editor` role.\n\n---\n\n## What gets versioned\n\n| Source | Versioned? |\n|---|---|\n| All user-defined Arc models | ✅ Yes |\n| arc-cms models (users, pages, groups, media, pageblocks) | ✅ Yes |\n| `_arc_versions` itself | ❌ No (recursion prevention) |\n| Tables in `excludeModels` | ❌ No (opt-out) |\n\n---\n\n## Performance\n\n| Operation | Time | Notes |\n|---|---|---|\n| Record mutation | O(log N) INSERT + O(1) main op | Prepared statement, \u003c 0.1ms |\n| History fetch | O(log N) | Covered by `(modelName, recordId, id DESC)` index |\n| Revert | O(log N) lookup + O(1) UPDATE | |\n| Trim (cleanup) | O(K) DELETE, async | Never blocks mutations |\n\nStorage is bounded to `maxVersionsPerRecord × number_of_models × avg_row_bytes`.\n\n---\n\n## TypeScript\n\n```ts\nimport type { ArcVersion, VersioningConfig, ArcConfigWithVersioning } from 'arc-versioning'\n\nconst version: ArcVersion = {\n  id: 1,\n  modelName: 'posts',\n  recordId: '42',\n  action: 'update',    // 'create' | 'update' | 'delete' | 'revert'\n  data: '{\"title\":\"Hello\"}',\n  userId: 'u_1',\n  createdAt: '2026-06-01T12:00:00Z',\n  userName: 'Alice',   // enriched by history API\n}\n```\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE) © arc-language\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farc-language%2Farc-versioning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farc-language%2Farc-versioning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farc-language%2Farc-versioning/lists"}