How agrostar/zzapi works
Main Components
• Core Library Modules (located in the “src” directory):
• Request Execution: Modules such as executeRequest.ts and constructCurl.ts handle turning YAML definitions into actual API calls.
• Parsing & Data Merging: Files like parseBundle.ts, convertPostman.ts, mergeData.ts, and replaceVars.ts indicate that the library parses API bundle files and merges in environment variables.
• Variable Management: captureVars.ts, variables.ts, and variableParser.ts represent modules dedicated to managing and capturing dynamic variables.
• Type Checking and Validation: checkTypes.ts and associated utility functions (in src/utils/typeUtils.ts) lend structure to how data is validated.
• Models: models.ts likely contains core definitions of the data structures used across the library.
• Test Runner: runTests.ts exists for executing tests, further supported by test utilities and integration tests in the “tests” directory.
• Schemas: The “schemas” directory contains JSON schemas (zzapi-bundle.schema.json and zzapi-varset.schema.json) to validate the YAML bundle and variable set files.
• External Tools: Although not part of the repository, the README mentions a VS Code extension and a CLI tool that use this library, making them external clients of the library.
• Documentation & Examples: The “docs” and “examples” directories provide specification details and sample configurations of how the API bundles and variable sets are formatted.
Relationships and Interactions
• Data Flow from Input to Execution:
• The system starts with API configuration files (YAML bundles and variable sets) defined by the user.
• These files are parsed by the library (using parseBundle.ts and convertPostman.ts) and validated against provided JSON schemas.
• The parsed data is then processed by merging variables (mergeData.ts) and replacing placeholders (replaceVars.ts).
• Once the API requests are fully prepared, they flow into the Request Execution module (via executeRequest.ts and constructCurl.ts), which handles sending requests and optionally capturing responses (captureVars.ts).
• Testing Workflow:
• The runTests.ts module – along with supporting modules in the tests directory – manages automated API tests, checking responses against expected outputs without requiring additional code from the end user.
• External Integration:
Architectural Patterns and Technologies
• Modularity: The project is divided into well-separated modules responsible for parsing, execution, variable management, and testing.
• Schema-Based Validation: Using JSON schemas for validating configuration files is an important design principle.
• CLI/Extension Integration: The library’s API is designed for easy integration with other tools, emphasizing a clear separation between core functionality and presentation/UI layers.
• Utilization of TypeScript: The use of TypeScript (as evidenced by the .ts files, tsconfig.json, and tsup.config.ts) ensures type safety and better modularity.