{"id":41209573,"url":"https://github.com/yididev/verity","last_synced_at":"2026-05-31T22:01:27.257Z","repository":{"id":324445145,"uuid":"1097247996","full_name":"YidiDev/verity","owner":"YidiDev","description":"Framework-agnostic data layer that enforces server-as-source-of-truth. Handles caching, staleness, and directive-driven updates so UIs render truth-state without optimistic lies. Works with Alpine, React, Vue, and Svelte.","archived":false,"fork":false,"pushed_at":"2026-05-27T23:43:56.000Z","size":583,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-28T01:22:19.935Z","etag":null,"topics":["data-structures","ui-dataflow","ui-framework"],"latest_commit_sha":null,"homepage":"http://verity.yidi.sh/","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/YidiDev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","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},"funding":{"github":"YidiDev"}},"created_at":"2025-11-15T20:11:12.000Z","updated_at":"2026-05-27T23:44:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/YidiDev/verity","commit_stats":null,"previous_names":["yididev/verity"],"tags_count":36,"template":false,"template_full_name":null,"purl":"pkg:github/YidiDev/verity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YidiDev%2Fverity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YidiDev%2Fverity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YidiDev%2Fverity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YidiDev%2Fverity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YidiDev","download_url":"https://codeload.github.com/YidiDev/verity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YidiDev%2Fverity/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33750474,"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-05-31T02:00:06.040Z","response_time":95,"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-structures","ui-dataflow","ui-framework"],"created_at":"2026-01-22T22:53:30.088Z","updated_at":"2026-05-31T22:01:27.252Z","avatar_url":"https://github.com/YidiDev.png","language":"JavaScript","funding_links":["https://github.com/sponsors/YidiDev"],"categories":[],"sub_categories":[],"readme":"# Verity\n\n\u003e **One strong idea:** the server is the only source of truth.  \n\u003e **One clear boundary:** **truth-state** (server-owned) is not the same as **view-state** (client-owned).  \n\u003e **One purpose:** a composable data layer that mediates between them--protocol-agnostic, framework-agnostic, and honest.\n\nVerity is the **backend of your frontend**. It sits between your server and view layer, handling caching, staleness, fan-out, and directive processing so your UI can focus purely on rendering.\n\n## The Problem\n\nModern frontends blur two fundamentally different kinds of state:\n\n- **Truth-state** -- authoritative data whose source of truth is the server (domain models, records, counters, permissions)\n- **View-state** -- ephemeral client concerns (which menu is open, which row is expanded, which tab has focus)\n\nMost frameworks *can* represent both, but they rarely enforce a practical boundary. Teams end up mixing \"what the server says\" with \"what the UI is doing,\" then try to paper over races and stale views with **optimistic updates**. That creates flicker, mismatch, and user distrust.\n\n## The Solution\n\n**Verity separates the lanes:**\n\n1. The **server** owns data integrity and business logic\n2. **Verity** is the **backend of the frontend**: it fetches, coalesces, tracks staleness, reacts to server **directives**, and exposes stable references to truth-state\n3. The **view layer** renders those references and manages local view-state--**without** fetching, caching, guessing, or coordinating invalidation\n\nThis separation isn't just conceptual--it shows up in Verity's public API, internal guarantees, and strict UX policy.\n\n## Core Principles\n\n**Server Truth Only**  \nThe UI changes **after** the server confirms change. Unknowns render as skeletons; work in progress renders as spinners. No temporary lies, no speculation.\n\n**Directive-Driven Updates**  \nRather than pushing DOM or raw events, servers emit **semantic directives**--small, transport-agnostic messages that describe what should be refreshed. Directives decouple server logic from UI structure and compose beautifully: mutation responses provide immediate local echo, while **fan-out over SSE** keeps other tabs and devices consistent.\n\n**Levels \u0026 Minimal Fetching**  \nA single entity can be viewed at different detail levels (`simplified`, `expanded`). Verity lets you declare conversion graphs so one fetch can satisfy multiple levels without redundant network calls. When directives arrive, Verity computes the minimal set of refetches needed to return to truth.\n\n**Framework-Agnostic Core**  \nVerity exposes stable refs (`{ data, meta }`) and a subscribe API. Thin adapters wire that into Alpine, React, Vue, or Svelte with identical semantics. The value lives in the core, not the glue.\n\n**Honest by Design**  \nPerceived snappiness never justifies lying. If your product needs \"instant echo,\" build endpoints that return the truth immediately--don't fake it in the client.\n\n## Installation\n\n### Via CDN (no build tools)\n\nDrop a script tag and go. Works with jsDelivr, unpkg, or bundle.run:\n\n```html\n\u003c!-- jsDelivr --\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/verity-dl@latest/dist/core.umd.js\"\u003e\u003c/script\u003e\n\n\u003c!-- unpkg --\u003e\n\u003cscript src=\"https://unpkg.com/verity-dl@latest/dist/core.umd.js\"\u003e\u003c/script\u003e\n\n\u003c!-- bundle.run --\u003e\n\u003cscript src=\"https://bundle.run/verity-dl@latest/dist/core.umd.js\"\u003e\u003c/script\u003e\n```\n\nThe UMD build exposes `window.DLCore` globally.\n\n### Via npm / yarn (for bundlers)\n\n```bash\n# npm\nnpm install verity-dl\n\n# yarn\nyarn add verity-dl\n```\n\n```javascript\n// ESM import\nimport { init, createType, createCollection, fetchItem } from 'verity-dl';\n\n// CommonJS require\nconst { init, createType, createCollection, fetchItem } = require('verity-dl');\n```\n\n### TypeScript\n\nThe package ships bundled type declarations. No `@types/` package needed.\n\n```typescript\nimport {\n  init,\n  createType,\n  createCollection,\n  fetchItem,\n  fetchCollection,\n  onChange,\n  type ItemRef,\n  type CollectionRef,\n  type Directive,\n  type SseConfig,\n} from 'verity-dl';\n\n// Full IntelliSense and type safety out of the box\ncreateType('todo', {\n  fetch: async (id: unknown): Promise\u003c{ id: string; title: string }\u003e =\u003e {\n    const res = await fetch(`/api/todos/${id}`);\n    return res.json();\n  },\n  stalenessMs: 30_000,\n});\n```\n\n## Quick Start\n\n### Minimal example (no framework)\n\n```html\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/verity-dl@latest/dist/core.umd.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  DLCore.createCollection('todos', {\n    fetch: () =\u003e fetch('/api/todos').then(r =\u003e r.json()),\n  });\n\n  DLCore.createType('todo', {\n    fetch: (id) =\u003e fetch(`/api/todos/${id}`).then(r =\u003e r.json()),\n  });\n\n  DLCore.init({ sse: { url: '/api/events' } });\n\n  // Fetch and observe\n  const ref = DLCore.fetchCollection('todos');\n  DLCore.onChange(() =\u003e {\n    console.log('Todos:', ref.data, 'Loading:', ref.meta.isLoading);\n  });\n\u003c/script\u003e\n```\n\n### Run examples locally\n\nThe repository includes full-stack examples built with Flask:\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n\n# Run an example\npython verity/examples/invoices_alpine/app.py\n# or try the manufacturing control room\npython verity/examples/manufacturing_monitor/app.py\n```\n\n### Explore documentation\n\nVisit [verity.yidi.sh](https://verity.yidi.sh) or run locally:\n\n```bash\nmkdocs serve\n```\n\nThen open \u003chttp://127.0.0.1:8000\u003e to dive into the mental model, guides, and API reference.\n\n## How This Differs from Alternatives\n\n### vs htmx / LiveView / Turbo Streams\nServer is the source of truth, but server dictates DOM, tightly coupling backend to view structure.\n**Verity** pushes **data intent** (directives) and keeps **view-state** client-owned.\n\n### vs TanStack Query / RTK Query / Apollo\nMature caches with good invalidation tooling and multi-framework support, but optimistic updates are first-class, invalidation semantics are app-defined glue, and there is no concept of levels + conversion planning.\n**Verity** bakes invalidation semantics into a **server-authored contract** and plans minimal refetches.\n\n### vs Roll-Your-Own Store + Fetch\nMaximum control, but you re-implement coalescing, latest-wins, push integration, multi-client convergence, and UX semantics every time.\n**Verity** exists to be the boring, correct default.\n\n## Design Guarantees\n\n- **Latest-wins**: stale network results won't clobber newer state\n- **Coalesced**: identical in-flight requests reuse one promise\n- **Deterministic**: the same sequence of directives + responses yields the same cache\n- **Isolated**: truth-state doesn't leak view concerns; view-state doesn't influence server truth\n- **Pluggable**: fetchers and directive sources are replaceable without touching views\n\n## When to Use Verity\n\nUse Verity where **server truth matters**--shared, audited, multi-client data. Keep purely local UIs (menus, focus, modals) in your framework's own state.\n\n**Smell test:** if changing tabs or reloading should reset it, it's probably view-state. If a coworker on another device must see it, it's truth-state.\n\n## Development\n\n```bash\n# Install dependencies\ncorepack enable\nyarn install\n\n# Run all checks (typecheck + lint + test)\nyarn check\n\n# Individual commands\nyarn typecheck      # TypeScript type checking\nyarn lint           # ESLint\nyarn test           # Vitest\nyarn build          # Vite production build\n```\n\n## Repository Layout\n\n```text\nsrc/\n  core/               # TypeScript source (modular)\n  adapters/           # Framework adapters (Alpine, React, Vue, Svelte)\n  devtools/           # In-browser devtools panel\ndist/                 # Built output (ESM, UMD, .d.ts)\ntests/                # Vitest test suite\nverity/\n  examples/           # Full-stack Flask reference applications\ndocs/                 # MkDocs content (philosophy, guides, reference)\n```\n\n## Next Steps\n\n1. Read [Philosophy](https://verity.yidi.sh/philosophy) for the full mental model\n2. Understand [Architecture](https://verity.yidi.sh/architecture) to see how the three layers interact\n3. Explore [Truth-State vs View-State](https://verity.yidi.sh/concepts/truth-vs-view-state) to master the core distinction\n4. Follow [Getting Started](https://verity.yidi.sh/guides/getting-started) to wire Verity into a new project\n5. Study the [examples](https://verity.yidi.sh/examples) to see patterns in action\n\n## License\n\nMIT. Build trustworthy, data-heavy apps with a simple, honest UI.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyididev%2Fverity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyididev%2Fverity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyididev%2Fverity/lists"}