g1-ts-common-packages/memory-bank/techContext.md

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

# 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:

cd packages/package-name
pnpm build

To build all packages:

pnpm -r build

Testing Packages

To run tests for a specific package:

cd packages/package-name
pnpm test

To test all packages:

pnpm -r test

Publishing Packages

For team members with write access to the repository:

# 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)