diff --git a/README.md b/README.md index da3e527..1b30494 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,8 @@ A custom Server-Sent Events (SSE) client that supports headers and bypasses cert - Works in both browser and Node.js environments - Provides connection management utilities +[View SSE Client Documentation](packages/sse-client/README.md) + ## Getting Started ### Prerequisites diff --git a/memory-bank/README.md b/memory-bank/README.md new file mode 100644 index 0000000..11a44c3 --- /dev/null +++ b/memory-bank/README.md @@ -0,0 +1,100 @@ +# Memory Bank + +I am an expert software engineer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I MUST read ALL memory bank files at the start of EVERY task - this is not optional. + +## Quick Reference (Project Overview) + + +### Important Workflow Preferences +- **Git Commits**: NEVER commit without asking the user first +- **Completion Reminders**: Remind/ask the user when big sections have been done and tested +- **Command Line**: Use PowerShell for all command-line operations (Windows environment) +- **Development Server**: NEVER run the server unless specifically asked, as user often runs it in the background + +### Documentation Sources +- **AI Agent Documentation** (`/docs/ai/`): Concise, up-to-date docs designed for AI agents + +## Memory Bank Structure + +The Memory Bank consists of core files and optional context files, all in Markdown format. Files build upon each other in a clear hierarchy: + +flowchart TD + PB[projectbrief.md] --> PC[productContext.md] + PB --> SP[systemPatterns.md] + PB --> TC[techContext.md] + +### Core Files (Required) +1. `projectbrief.md` + - Foundation document that shapes all other files + - Created at project start if it doesn't exist + - Defines core requirements and goals + - Source of truth for project scope + +2. `systemPatterns.md` + - System architecture + - Key technical decisions + - Design patterns in use + - Component relationships + - Critical implementation paths + +3. `techContext.md` + - Technologies used + - Development setup + - Technical constraints + - Dependencies + - Tool usage patterns + +### Additional Context +Create additional files/folders within memory-bank/ when they help organize: +- Complex feature documentation +- Integration specifications +- API documentation +- Testing strategies +- Deployment procedures + +## Core Workflows + +### Plan Mode +flowchart TD + Start[Start] --> ReadFiles[Read Memory Bank] + ReadFiles --> CheckFiles{Files Complete?} + + CheckFiles -->|No| Plan[Create Plan] + Plan --> Document[Document in Chat] + + CheckFiles -->|Yes| Verify[Verify Context] + Verify --> Strategy[Develop Strategy] + Strategy --> Present[Present Approach] + +### Act Mode +flowchart TD + Start[Start] --> Context[Check Memory Bank] + Context --> Update[Update Documentation] + Update --> Execute[Execute Task] + Execute --> Document[Document Changes] + +## Documentation Updates + +Memory Bank updates occur when: +1. Discovering new project patterns +2. After implementing significant changes +3. When user requests with **update memory bank** (MUST review ALL files) +4. When context needs clarification + +flowchart TD + Start[Update Process] + + subgraph Process + P1[Review ALL Files] + P2[Document Current State] + P3[Clarify Next Steps] + P4[Document Insights & Patterns] + + P1 --> P2 --> P3 --> P4 + end + + Start --> Process + +Note: When triggered by **update memory bank**, I MUST review every memory bank file, even if some don't require updates. Focus particularly on activeContext.md and progress.md as they track current state. + +REMEMBER: After every memory reset, I begin completely fresh. The Memory Bank is my only link to previous work. It must be maintained with precision and clarity, as my effectiveness depends entirely on its accuracy. diff --git a/memory-bank/projectbrief.md b/memory-bank/projectbrief.md new file mode 100644 index 0000000..fb61ba8 --- /dev/null +++ b/memory-bank/projectbrief.md @@ -0,0 +1,50 @@ +# Project Brief: G1 TypeScript Common Packages + +## Project Overview +G1 TypeScript Common Packages is a monorepo containing common TypeScript packages used across Generation One projects. The repository is public, making it easier to share and collaborate on common utilities. + +## Core Requirements + +1. **Shared Utilities**: Create and maintain reusable TypeScript packages that can be shared across Generation One projects. +2. **Public Access**: Keep the repository public to facilitate sharing and collaboration. +3. **Package Management**: Use pnpm workspaces for efficient package management. +4. **TypeScript Support**: Ensure all packages have proper TypeScript typings and support. +5. **Documentation**: Maintain comprehensive documentation for each package. +6. **Testing**: Include tests for all packages to ensure reliability. +7. **CI/CD**: Implement automated testing and publishing workflows. + +## Current Packages + +### SSE Client (`@g1/sse-client`) +A custom Server-Sent Events (SSE) client that supports headers and bypasses certificate issues. + +**Key Features:** +- Custom headers support for SSE connections +- SSL certificate validation bypass +- Automatic reconnection with exponential backoff +- Connection management +- Event handling +- Works in both browser and Node.js environments + +## Project Goals + +1. **Reliability**: Create robust, well-tested packages that can be relied upon in production environments. +2. **Reusability**: Design packages to be easily reused across different projects. +3. **Maintainability**: Ensure code is well-documented and follows best practices for long-term maintenance. +4. **Extensibility**: Design packages to be easily extended or customized for specific use cases. +5. **Compatibility**: Ensure packages work across different environments (browser, Node.js) where applicable. + +## Future Direction + +1. **Additional Packages**: Add more common utilities as needed by Generation One projects. +2. **Version Management**: Maintain proper versioning for all packages. +3. **Community Contributions**: Encourage contributions from the community. + +## Project Scope + +This project focuses solely on creating and maintaining common TypeScript packages. It does not include: +- Application-specific code +- UI components or frameworks +- Backend services or APIs + +The scope is intentionally limited to ensure the packages remain focused, reusable, and maintainable. diff --git a/memory-bank/systemPatterns.md b/memory-bank/systemPatterns.md new file mode 100644 index 0000000..97a70d0 --- /dev/null +++ b/memory-bank/systemPatterns.md @@ -0,0 +1,182 @@ +# System Patterns + +This document outlines the system architecture, key technical decisions, and design patterns used in the G1 TypeScript Common Packages repository. + +## System Architecture + +The repository follows a monorepo architecture using pnpm workspaces: + +``` +g1-ts-common-packages/ +├── packages/ # All packages are stored here +│ ├── sse-client/ # Server-Sent Events client package +│ └── [future-packages]/ # Additional packages will be added here +├── scripts/ # Utility scripts for the repository +├── docs/ # Documentation +└── .github/workflows/ # CI/CD workflows +``` + +Each package within the monorepo is designed to be: +- **Independent**: Can be used without other packages from the monorepo +- **Focused**: Solves a specific problem domain +- **Well-documented**: Includes comprehensive documentation +- **Well-tested**: Includes unit tests + +## Key Technical Decisions + +### 1. Monorepo Structure +- **Decision**: Use a monorepo structure with pnpm workspaces +- **Rationale**: + - Simplifies management of multiple related packages + - Enables sharing of configuration and tooling + - Facilitates coordinated changes across packages + - Reduces duplication of dependencies + +### 2. Package Scope +- **Decision**: Use the `@g1` scope for all packages +- **Rationale**: + - Provides namespace isolation + - Makes it clear that packages belong to Generation One + - Prevents name collisions with other packages + +### 3. Package Versioning +- **Decision**: Start packages at version 0.2.0 +- **Rationale**: + - Follows Generation One's standard starting version + - Allows for pre-1.0 breaking changes as packages mature + +### 4. Publishing Strategy +- **Decision**: Publish packages to Gitea registry +- **Rationale**: + - Keeps packages within Generation One's infrastructure + - Provides access control for private packages (if needed in the future) + - Simplifies CI/CD integration + +### 5. TypeScript First +- **Decision**: Use TypeScript for all packages +- **Rationale**: + - Provides type safety + - Improves developer experience + - Enables better tooling and IDE support + - Reduces runtime errors + +## Design Patterns + +### SSE Client Package + +The SSE Client package demonstrates several design patterns: + +#### 1. Singleton Pattern +- Used in the `SSEConnectionManager` to ensure only one instance manages all connections +- Provides a global point of access to the connection manager + +```typescript +export class SSEConnectionManager { + private static instance: SSEConnectionManager; + + private constructor() {} + + public static getInstance(): SSEConnectionManager { + if (!SSEConnectionManager.instance) { + SSEConnectionManager.instance = new SSEConnectionManager(); + } + return SSEConnectionManager.instance; + } + + // ... +} +``` + +#### 2. Factory Pattern +- Helper functions like `getSSEConnection` act as factories to create or retrieve SSE client instances +- Simplifies the creation and management of SSE connections + +```typescript +export function getSSEConnection(url: string, id: string, options: SSEClientOptions = {}): SSEClient { + return SSEConnectionManager.getInstance().getConnection(url, id, options); +} +``` + +#### 3. Observer Pattern +- The SSE client implements an event-based system where clients can subscribe to events +- Uses the browser's `EventTarget` or a custom implementation in Node.js + +```typescript +public on(eventName: string, listener: (event: any) => void): SSEClient { + if (!this.eventListeners.has(eventName)) { + this.eventListeners.set(eventName, new Set()); + } + + this.eventListeners.get(eventName)!.add(listener); + + // ... + + return this; +} +``` + +#### 4. Options Pattern +- Uses an options object with defaults for configuration +- Allows for flexible and extensible configuration + +```typescript +export interface SSEClientOptions { + headers?: Record; + withCredentials?: boolean; + heartbeatTimeout?: number; + // ... +} + +const DEFAULT_OPTIONS: Required> = { + withCredentials: true, + heartbeatTimeout: 21600000, // 6 hours + // ... +}; +``` + +#### 5. Exponential Backoff Pattern +- Implements exponential backoff for reconnection attempts +- Helps prevent overwhelming the server during outages + +```typescript +private async reconnect(): Promise { + this.retryCount++; + + // Calculate delay with exponential backoff + const delayMs = Math.min( + this.options.initialRetryDelay * Math.pow(2, this.retryCount - 1), + this.options.maxRetryDelay + ); + + // ... +} +``` + +## Critical Implementation Paths + +### SSE Client Connection Flow + +1. **Initialization**: Create an SSE client with URL and options +2. **Connection**: Call `connect()` to establish the connection +3. **Event Handling**: Register event listeners with `on(eventName, listener)` +4. **Error Handling**: Automatic reconnection with exponential backoff +5. **Cleanup**: Close connection with `close()` or use automatic cleanup + +### SSE Client Connection Management + +1. **Get/Create Connection**: Use `getSSEConnection(url, id, options)` to get or create a connection +2. **Connection Reuse**: Connections are reused based on the provided ID +3. **Connection Cleanup**: Close specific connections with `closeSSEConnection(id)` or all with `closeAllSSEConnections()` +4. **Automatic Cleanup**: Set up with `setupSSECleanup()` to close connections on page unload + +## Component Relationships + +- **SSEClient**: Core class that handles the SSE connection and events +- **SSEConnectionManager**: Singleton that manages multiple SSE connections +- **Helper Functions**: Provide simplified access to the connection manager + - `getSSEConnection`: Gets or creates a connection + - `closeSSEConnection`: Closes a specific connection + - `closeAllSSEConnections`: Closes all connections + - `setupSSECleanup`: Sets up automatic cleanup +- **Debug Utilities**: Provide debug logging capabilities + - `debugLog`, `debugInfo`, `debugWarn`, `debugError` diff --git a/memory-bank/techContext.md b/memory-bank/techContext.md new file mode 100644 index 0000000..0e57832 --- /dev/null +++ b/memory-bank/techContext.md @@ -0,0 +1,221 @@ +# Technical Context + +This document outlines the technologies used, development setup, technical constraints, and dependencies for the G1 TypeScript Common Packages repository. + +## Technologies Used + +### Core Technologies + +| Technology | Purpose | Version | +|------------|---------|---------| +| TypeScript | Static typing for JavaScript | ^5.0.0 | +| Node.js | JavaScript runtime | 16+ | +| pnpm | Package manager | Latest | + +### Build & Development Tools + +| Tool | Purpose | +|------|---------| +| TypeScript Compiler | Compiles TypeScript to JavaScript | +| Jest | Testing framework | +| ESLint | Code linting | +| GitHub Actions | CI/CD workflows | + +### Dependencies + +#### SSE Client Package + +| Dependency | Purpose | +|------------|---------| +| event-source-polyfill | Polyfill for EventSource with custom headers support | + +## Development Setup + +### Prerequisites + +- Node.js 16+ +- pnpm (recommended) or npm + +### Installation + +```bash +# Clone the repository +git clone https://git.generation.one/GenerationOne/g1-ts-common-packages.git +cd g1-ts-common-packages + +# Install dependencies +pnpm install + +# Build all packages +pnpm build +``` + +### Repository Structure + +``` +g1-ts-common-packages/ +├── packages/ # All packages are stored here +│ ├── sse-client/ # Server-Sent Events client package +│ │ ├── src/ # Source code +│ │ ├── dist/ # Compiled output (generated) +│ │ ├── examples/ # Example usage +│ │ ├── __tests__/ # Tests +│ │ ├── package.json # Package configuration +│ │ └── tsconfig.json # TypeScript configuration +│ └── [future-packages]/ # Additional packages will be added here +├── scripts/ # Utility scripts for the repository +│ ├── publish-package.sh # Script for publishing packages +│ └── setup-deploy-key.sh # Script for setting up deploy keys +├── docs/ # Documentation +│ └── DEPLOY_KEYS.md # Documentation for deploy keys +└── .github/workflows/ # CI/CD workflows +``` + +### Package Structure (SSE Client) + +``` +sse-client/ +├── src/ # Source code +│ ├── index.ts # Main entry point +│ ├── sseClient.ts # SSE client implementation +│ └── utils/ # Utility functions +│ └── debug.ts # Debug utilities +├── examples/ # Example usage +│ ├── angular-order-tracking.component.ts +│ ├── browser-script.html +│ ├── express-sse-proxy.js +│ ├── fastify-sse-proxy.js +│ ├── nextjs-sse-proxy.ts +│ ├── nodejs-sse-client.js +│ ├── order-tracking.ts +│ ├── react-order-tracking.tsx +│ └── vue-order-tracking.vue +├── __tests__/ # Tests +│ └── sseClient.test.ts # SSE client tests +├── dist/ # Compiled output (generated) +├── package.json # Package configuration +├── tsconfig.json # TypeScript configuration +├── jest.config.js # Jest configuration +├── LICENSE # License file +├── README.md # Package documentation +├── PUBLISHING.md # Publishing instructions +└── SUMMARY.md # Package summary +``` + +## Development Workflow + +### Building Packages + +To build a specific package: + +```bash +cd packages/package-name +pnpm build +``` + +To build all packages: + +```bash +pnpm -r build +``` + +### Testing Packages + +To run tests for a specific package: + +```bash +cd packages/package-name +pnpm test +``` + +To test all packages: + +```bash +pnpm -r test +``` + +### Publishing Packages + +For team members with write access to the repository: + +```bash +# Set your access token +export GITEA_TOKEN="your-token-here" + +# Publish with a version bump +./scripts/publish-package.sh packages/sse-client patch +``` + +Version options: +- `patch` - Increment the patch version (0.2.0 → 0.2.1) +- `minor` - Increment the minor version (0.2.0 → 0.3.0) +- `major` - Increment the major version (0.2.0 → 1.0.0) +- `version:x.y.z` - Set a specific version +- `none` - Keep the current version + +## Technical Constraints + +### Browser Compatibility + +- The SSE client package is designed to work in modern browsers and Node.js environments +- For older browsers, the event-source-polyfill is used to provide EventSource functionality + +### Node.js Compatibility + +- Packages are designed to work with Node.js 16+ +- SSL certificate validation bypass is only available in Node.js environments + +### Package Size + +- Packages should be kept as small as possible to minimize bundle size +- Dependencies should be carefully chosen to avoid bloating the package + +### API Design + +- APIs should be designed to be intuitive and consistent +- Breaking changes should be avoided when possible, especially after reaching version 1.0.0 +- When breaking changes are necessary, they should be clearly documented + +## Tool Usage Patterns + +### pnpm Workspace Commands + +- `pnpm -r ` - Run a command in all packages +- `pnpm -r --filter ` - Run a command in a specific package + +### Publishing Workflow + +1. Make changes to a package +2. Update tests and documentation +3. Run tests to ensure everything works +4. Use the publish script to publish the package with a version bump +5. The script will: + - Build the package + - Update the version + - Publish to the Gitea registry + - Create a git tag + +### CI/CD Workflow + +The repository uses GitHub Actions for CI/CD: + +1. On push to main or pull request: + - Build all packages + - Run tests for all packages +2. On release: + - Publish packages to the Gitea registry + +## Environment Variables + +| Variable | Purpose | +|----------|---------| +| GITEA_TOKEN | Access token for publishing packages to the Gitea registry | +| GITEA_DEPLOY_KEY | SSH deploy key for CI/CD workflows | + +## Documentation Standards + +- Each package should have: + - A README.md with usage examples + - JSDoc comments for all public APIs + - A SUMMARY.md with a brief overview + - A PUBLISHING.md with publishing instructions (if applicable)