gittrends-app/core

Purpose and Public Entry Points

@gittrends-app/core is a Node.js 20+ TypeScript library that retrieves GitHub GraphQL data and normalizes it into runtime-validated domain entities. Consumers import its public API from src/index.ts, notably GithubClient, GithubService, the Service contract, and optional caching/buffering decorators. Runnable usage patterns are in samples/search-repositories.ts and samples/get-resources.ts.

Service Abstraction and Composition

Service defines the application-facing retrieval contract; GithubService implements it against GitHub. Services are deliberately composable: callers can wrap a source service with caching and buffered iteration without changing the consumer API.

• src/services/Service.ts

• src/services/github/GithubService.ts

• src/services/CacheService.ts

• src/services/BufferedService.ts

PassThroughService provides the base delegation pattern used by wrappers: request flow is consumer → optional decorators → GitHub-backed source.

GitHub Transport Boundary

GithubClient owns the external GitHub API boundary: API base URL, token authentication, request timeout, and shared maximum concurrency across primary queries and nested enrichment. Query execution is centralized by QueryRunner, isolating GraphQL request/error behavior from resource-specific lookup logic.

• src/services/github/GithubClient.ts

• src/services/github/graphql/QueryRunner.ts

• src/helpers/throttler.ts

GitHub GraphQL is the only identified external service; no application database or server runtime is present.

GraphQL Query Construction and Lookup Layer

Resource retrieval is modeled as lookups that generate/query distinct GitHub GraphQL shapes: repositories, search, users, issues, pull requests, commits, discussions, releases, tags, and connection-based related data. Lookup implementations sit between the service API and GraphQL runner, forming the main query specialization boundary.

• src/services/github/graphql/lookups/Lookup.ts

• src/services/github/graphql/lookups/RepositoryLookup.ts

• src/services/github/graphql/lookups/ConnectionLookup.ts

GraphQL fragments consolidate reusable selection sets and allow lookup responses to include nested domain data consistently.

• src/services/github/graphql/fragments/Fragment.ts

• src/services/github/graphql/fragments/RepositoryFragment.ts

• src/services/github/graphql/fragments/TimelineItemFragment.ts

Resource Iteration, Pagination, and Enrichment

The resources() API exposes async page iteration. Pagination standardizes emitted data plus opaque continuation cursor, per_page, and has_more; callers feed the cursor back to resume. GitHub resource handlers connect named resources to their lookups and apply resource-specific mapping/enrichment.

• src/services/pagination.ts

• src/services/github/resources/repos.ts

• src/services/github/resources/enrichment.ts

Nested enrichment—such as comments or review-thread/timeline-related data—remains behind this resource layer and shares client concurrency controls rather than bypassing transport governance.

Domain Entity Boundary

GitHub GraphQL output is transformed into entity models representing repository activity and actors. Zod-backed entity schemas are the runtime-validation boundary, preventing raw or malformed API responses from leaking through the public service API.

• src/entities/index.ts

• src/entities/Repository.ts

• src/entities/Issue.ts

Common GraphQL/domain concepts—node identity, actors, comments, reactions, and repository-scoped nodes—are factored into base entity schemas.

• src/entities/base/Node.ts

• src/entities/base/GitActorSchema.ts

• src/entities/base/RepositoryNode.ts

Cache and Buffer Operational Semantics

CacheService treats cache reads/writes as best effort: backend failure must not fail the underlying GitHub request. BufferedService batches/controls iteration behavior while preserving the Service interface. These wrappers are infrastructure-neutral: cache persistence is supplied by the consuming application through the exported cache interface.

• src/services/CacheService.ts

• src/services/BufferedService.ts

• src/services/PassThroughService.ts