{"id":48655899,"url":"https://github.com/magicmark/mock-spec-demo","last_synced_at":"2026-04-10T09:12:45.341Z","repository":{"id":342722282,"uuid":"1167884585","full_name":"magicmark/mock-spec-demo","owner":"magicmark","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-26T18:12:24.000Z","size":95,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T07:44:15.176Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magicmark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-02-26T19:40:33.000Z","updated_at":"2026-03-26T18:12:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/magicmark/mock-spec-demo","commit_stats":null,"previous_names":["magicmark/mock-spec-demo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/magicmark/mock-spec-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicmark%2Fmock-spec-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicmark%2Fmock-spec-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicmark%2Fmock-spec-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicmark%2Fmock-spec-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magicmark","download_url":"https://codeload.github.com/magicmark/mock-spec-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magicmark%2Fmock-spec-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31636078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"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":[],"created_at":"2026-04-10T09:12:43.788Z","updated_at":"2026-04-10T09:12:45.324Z","avatar_url":"https://github.com/magicmark.png","language":"TypeScript","readme":"# GraphQL @mock Directive Demo\n\n**Live demo: https://mock-spec-demo.larah.me/**\n\nThis project implements the [GraphQL @mock directive specification](https://public.larah.me/~mark/MockSpec.wip.html) using Apollo Client with React and Vite.\n\n## What is the @mock Directive?\n\nThe `@mock` directive allows GraphQL clients to return mocked data for fields or entire operations, enabling:\n\n- **Parallel Development**: Frontend and backend teams can work simultaneously\n- **Testing Different States**: Easily test loading, error, and edge case scenarios\n- **Offline Development**: Work without backend availability\n\n## Features Implemented\n\n### 1. Operation-Level Mocking\nApply `@mock` to the entire operation - no network request is sent:\n\n```graphql\nquery GetCountries @mock(variant: \"top-three\") {\n  countries {\n    code\n    name\n    capital\n    emoji\n  }\n}\n```\n\n### 2. Field-Level Mocking\nApply `@mock` to specific fields - other fields fetch from real API:\n\n```graphql\nquery GetCountry($code: ID!) {\n  country(code: $code) {\n    code\n    name\n    capital @mock(variant: \"fictional-capital\")\n    currency\n  }\n}\n```\n\n### 3. Mock File Structure\nMock data is stored in JSON files following the spec:\n\n```json\n{\n  \"fictional-capital\": {\n    \"data\": \"Wakanda City\",\n    \"__appliesTo__\": \"Country.capital\",\n    \"__description__\": \"A fictional capital city name for testing\"\n  }\n}\n```\n\n## Project Structure\n\n```\napollo-mock-app/\n├── src/\n│   ├── apollo/\n│   │   ├── client.ts          # Apollo Client setup\n│   │   ├── mockLink.ts        # Custom Apollo Link implementing @mock\n│   │   └── mockRegistry.ts    # Mock file registry\n│   ├── queries/\n│   │   ├── countries.ts       # GraphQL queries\n│   │   └── __graphql_mocks__/\n│   │       ├── GetCountry.json\n│   │       └── GetCountries.json\n│   ├── App.tsx                # Demo UI\n│   └── main.tsx\n└── package.json\n```\n\n## How It Works\n\n### MockLink Implementation\n\nThe `MockLink` class is a custom Apollo Link that:\n\n1. **Detects @mock directives** in GraphQL operations\n2. **For operation-level mocks**: Returns mock data directly, bypassing the network\n3. **For field-level mocks**:\n   - Strips `@mock` directives from the query\n   - Sends the modified query to the server\n   - Merges mock data into the response\n\n### Key Implementation Details\n\n- Uses the GraphQL `visit` API to traverse and transform operation AST\n- Reads mock data from JSON files at build time\n- Validates mock variants exist and provides helpful error messages\n- Supports multiple mock variants per field/operation\n\n## Running the Demo\n\n```bash\n# Install dependencies\npnpm install\n\n# Start dev server\npnpm dev\n```\n\nVisit http://localhost:5173 and try the different demos:\n\n1. **Operation-Level Mock**: Click \"Execute Query\" and note NO network request in DevTools\n2. **Real API**: See the POST request to the countries API\n3. **Field-Level Mock**: Note the request is sent, but `capital` is mocked\n4. **Single Country**: All data from real API\n\n## Mock File Format\n\nMock files follow this structure:\n\n```json\n{\n  \"variant-id\": {\n    \"data\": {\n      // The mock data matching the selection shape\n    },\n    \"errors\": [\n      // Optional GraphQL errors array\n    ],\n    \"extensions\": {\n      // Optional extensions object\n    },\n    \"__appliesTo__\": \"Type.field\",\n    \"__description__\": \"Description of this mock variant\",\n    \"__metadata__\": {\n      // Optional metadata\n    }\n  }\n}\n```\n\n## Deviations from Spec\n\n### Simplified Implementation\n- **Field stripping**: Currently keeps fields in the query but removes `@mock` directives. The spec suggests removing mocked selections entirely, but this simplified approach works for the demo.\n- **Schema awareness**: This implementation doesn't validate against a schema. A production implementation would need schema validation.\n\n### Missing Features (for production)\n- Bundler plugin to automatically collect and register mock files\n- Schema validation of mock data\n- Mock file hot-reloading in development\n- TypeScript types generation from mock files\n\n## Technologies Used\n\n- **React 19** + **TypeScript**\n- **Vite 7** for build tooling\n- **Apollo Client 4** for GraphQL\n- **graphql-tag** for query parsing\n- Test API: https://countries.trevorblades.com/\n\n## Learn More\n\n- [GraphQL Mock Spec](../graphql-mock-spec/Spec.md)\n- [Apollo Client Links](https://www.apollographql.com/docs/react/api/link/introduction/)\n- [GraphQL Visitor Pattern](https://graphql.org/graphql-js/language/#visit)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagicmark%2Fmock-spec-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagicmark%2Fmock-spec-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagicmark%2Fmock-spec-demo/lists"}