GenerationOne/g1-ts-common-packages
GenerationOne/g1-ts-common-packages
4
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

documentation updates for memory bank

Browse Source
This commit is contained in:
hitchhiker 2025-04-16 22:33:33 +02:00
parent 3c448dd06f
commit 40da469730
5 changed files with 555 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -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 - Works in both browser and Node.js environments
- Provides connection management utilities - Provides connection management utilities
[View SSE Client Documentation](packages/sse-client/README.md)
## Getting Started ## Getting Started
### Prerequisites ### Prerequisites

100
memory-bank/README.md Normal file
View File

@ -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.

50
memory-bank/projectbrief.md Normal file
View File

@ -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.

182
memory-bank/systemPatterns.md Normal file
View File

@ -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<string, string>;
withCredentials?: boolean;
heartbeatTimeout?: number;
// ...
}
const DEFAULT_OPTIONS: Required<Omit<SSEClientOptions, 'headers'>> = {
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<void> {
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`

221
memory-bank/techContext.md Normal file
View File

@ -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 <command>` - Run a command in all packages
- `pnpm -r --filter <package> <command>` - 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)