How churchtools/churchtools-js-client works
Main components
• Core Library Module: Represent the primary functionality implemented in the src/ folder. This includes:
• churchtoolsClient (src/churchtoolsClient.ts): The gateway for setting the base URL, making API calls (get, post, put, etc.), and handling the login process.
• Logging (src/logging.ts): Handles log activation and possibly debugging output.
• Error Handling (src/errorHelper.ts and src/NoJSONError.ts): Utility functions for managing errors.
• URL Helpers (src/urlHelper.ts): Functions to validate and manipulate ChurchTools URLs.
• Examples: Indicate the two practical usage scenarios provided - one in Browser (examples/Browser) and one in Node.js (examples/Node.js) – to demonstrate how clients integrate the library.
• Test Suite: The tests contained in the test/ directory show how the library is expected to behave across its modules.
• Build & Config Components: Files like tsconfig.json, webpack.config.js, and configuration files (babel, eslint, prettier, etc.) which aren’t runtime components but show the compiled and coding standard architecture.
• External Dependencies: Based on the README, note dependencies such as axios, axios-cookiejar-support, and tough-cookie (for Node.js) that are needed when integrating the library in a Node.js environment.
Relationships and interactions
• At the core, the churchtoolsClient module acts as the interface between client applications and the ChurchTools API.
• How the client:
• Sets the base URL using setBaseUrl.
• Manages session cookies and authentication (with optional cookie jar support for Node.js).
• Automatically handles login renewal when sessions expire.
• Flow of API requests through exported HTTP methods (get, post, put, patch, deleteApi) which eventually communicate with ChurchTools’ REST API.
• Browser Integration: Illustrate that the bundled script is loaded into a web page and interacts with a ChurchTools instance.
Architectural patterns and design principles
• Abstraction: The library abstracts the complexities of API interactions and session management.
• Modularity: Separation in directories (src for source logic, test for validations, examples for integration), which clarifies component responsibilities.
• Extensibility: The design supports multiple instances through object instantiation (see example with ChurchtoolsClient in the README), so include a note on how multiple client objects can manage simultaneous API connections.
• Environment-specific configuration: Different handling for browser versus Node.js, indicating dependency injection and environment detection.
Relevant technologies and frameworks
• JavaScript/TypeScript as the main language.
• Build tools like webpack and TypeScript Compiler (tsconfig.json) that compile the source.
• ESLint, Prettier, and Babel for code quality and transformation.
• External libraries such as axios (for HTTP requests) and cookie-related modules in the Node.js context.