From 8d50cec36aa8b9f0df2748b47fa10b398b8b1786 Mon Sep 17 00:00:00 2001 From: Hristo Terezov Date: Mon, 3 Nov 2025 10:33:51 -0600 Subject: [PATCH 1/2] feat(exports): Export random and transport modules from main entry point All utility modules should be consistently accessible from the main package entry point to provide a unified API experience. Previously, random and transport were only available via subpath imports, creating inconsistency in how modules are accessed. --- index.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/index.ts b/index.ts index f13df49..8fee696 100644 --- a/index.ts +++ b/index.ts @@ -3,3 +3,5 @@ export * from './browser-detection'; export * from './jitsi-local-storage'; export * from './json'; export * from './polyfills'; +export * from './random'; +export * from './transport'; From d35b81e8073636c232231379a210e3777c907b65 Mon Sep 17 00:00:00 2001 From: Hristo Terezov Date: Mon, 3 Nov 2025 10:34:16 -0600 Subject: [PATCH 2/2] docs(claude): Update documentation to reflect current codebase state The documentation was outdated, referencing the project as a hybrid JavaScript/TypeScript codebase when it has been fully migrated to TypeScript. It also lacked information about the comprehensive test suite, improved CI/CD workflow, and the recent removal of the uri module. Updates include: - Full TypeScript migration completion - Comprehensive test suite with 100% coverage - Split CI workflow (lint, test, build jobs) - Codecov integration - Updated build output structure (dist/ directory) - Consistent module exports from main entry point - Removal of uri module documentation --- CLAUDE.md | 108 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 76 insertions(+), 32 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f87dc8d..b725bb7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,14 +4,20 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -This is `@jitsi/js-utils`, a collection of utility libraries for Jitsi JavaScript projects. The package is published to npm and provides shared functionality across the Jitsi ecosystem. This is a JavaScript/TypeScript hybrid project that exports ES6 modules. +This is `@jitsi/js-utils`, a collection of utility libraries for Jitsi JavaScript projects. The package is published to npm and provides shared functionality across the Jitsi ecosystem. This is a TypeScript project that exports ES6 modules. ## Development Commands -### Build and Type Generation -- `npm run build` - Compile TypeScript files using tsc -- `npm run gen-types` - Generate TypeScript declaration files in the `types/` directory -- `npm run prepack` - Runs both build and gen-types (automatically runs before publishing) +### Build +- `npm run build` - Compile TypeScript files to dist/ directory using tsc +- `npm run clean` - Remove the dist/ directory +- `npm run prepack` - Runs clean and build (automatically runs before publishing) + +### Testing +- `npm test` or `npm run test` - Run all tests using @web/test-runner +- `npm run test:watch` - Run tests in watch mode +- `npm run test:coverage` - Run tests with coverage reporting +- `npm run test:debug` - Run tests in manual debug mode with browser UI ### Linting - `npm run lint` - Run ESLint using @jitsi/eslint-config @@ -23,6 +29,8 @@ This is `@jitsi/js-utils`, a collection of utility libraries for Jitsi JavaScrip The codebase is organized as a collection of independent utility modules, each in its own directory: - **avatar/** - Avatar generation utilities + - Gravatar URL generation with email hashing + - **browser-detection/** - Browser and environment detection using ua-parser-js - Uses TypeScript with `BrowserDetection` class - Maps various browser names to Jitsi-specific naming conventions @@ -34,38 +42,56 @@ The codebase is organized as a collection of independent utility modules, each i - Emits 'changed' events on modifications - Supports serialization with optional key exclusion -- **json.ts** - Safe JSON parsing using @hapi/bourne +- **json.ts** - Safe JSON parsing using @hapi/bourne to prevent prototype pollution - **polyfills/** - Browser polyfills (currently querySelector-related) - **random/** - Random utility functions - - `roomNameGenerator.js` - Generate random room names - - `randomUtil.js` - General random utilities + - `roomNameGenerator.ts` - Generate random room names + - `randomUtil.ts` - General random utilities (hex strings, alphanumeric strings) - **transport/** - Message transport abstraction with request/response pattern - - `Transport.js` - Main transport class with event emitter pattern + - `Transport.ts` - Main transport class with event emitter pattern - Handles MESSAGE_TYPE_EVENT, MESSAGE_TYPE_REQUEST, MESSAGE_TYPE_RESPONSE - Implements pluggable backends via `setBackend()` - - `PostMessageTransportBackend.js` - postMessage-based backend - - `postis.js` - Third-party postMessage utility (used by PostMessageTransportBackend) - -- **uri/** - URI manipulation utilities - -### Entry Point -The main `index.js` re-exports all module functionality: + - `PostMessageTransportBackend.ts` - postMessage-based backend + - `postis.ts` - Third-party postMessage utility (used by PostMessageTransportBackend) + +### Entry Point and Exports +The main `index.ts` re-exports all utility modules: +- avatar +- browser-detection +- jitsi-local-storage +- json +- polyfills +- random +- transport + +All modules can be imported from the main package entry point: +```typescript +import { randomHexString, Transport, BrowserDetection } from '@jitsi/js-utils'; +``` + +Alternatively, subpath imports are also supported via the wildcard export pattern: +```typescript +import { randomHexString } from '@jitsi/js-utils/random'; +import { Transport } from '@jitsi/js-utils/transport'; +``` ### TypeScript Configuration - Target: ES6 modules - Strict mode enabled -- Declaration files generated in `types/` directory -- Only compiles specific TypeScript files (browser-detection, json.ts, polyfills) -- Most of the codebase remains in JavaScript +- Entire codebase written in TypeScript +- Build output goes to `dist/` directory with compiled .js and .d.ts files +- Source files remain in root directory structure (avatar/, browser-detection/, etc.) ### Package Publishing - Published as `@jitsi/js-utils` to npm with public access -- Main entry: `index.js` -- Type: ES module -- The `files` field in package.json controls what gets published +- Main entry: `dist/index.js` +- TypeScript types: `dist/index.d.ts` +- Package type: ES module +- Only the `dist/` directory is published (controlled by `files` field in package.json) +- Wildcard exports pattern allows subpath imports (e.g., `@jitsi/js-utils/random`) - AutoPublish workflow triggers on master branch pushes - Version bumping handled automatically by gh-action-bump-version @@ -75,18 +101,36 @@ The main `index.js` re-exports all module functionality: - `ua-parser-js` - User agent parsing for browser detection ## Coding Conventions -- Uses @jitsi/eslint-config with @babel/eslint-parser +- Uses @jitsi/eslint-config with TypeScript ESLint parser - JSDoc comments for all public APIs - Private members prefixed with underscore (_) - Event emitter pattern used for reactive components (JitsiLocalStorage, Transport) - -## TypeScript Migration -The project is gradually migrating from JavaScript to TypeScript. When adding features: -- New utilities should be written in TypeScript when possible -- When modifying existing JavaScript files, consider converting to TypeScript if it makes sense -- Update tsconfig.json `include` array when adding new TypeScript files -- Run `npm run build` and `npm run gen-types` to ensure type generation works +- All code written in TypeScript with strict type checking +- Follow existing patterns and naming conventions in the codebase ## Testing and CI -- CI runs on pull requests via GitHub Actions -- Linting is enforced in CI (no test suite currently defined) + +### Test Suite +- Comprehensive unit test suite with 100% code coverage +- Uses @web/test-runner with @esm-bundle/chai for assertions +- Tests organized alongside source files with `.spec.ts` extension +- 182+ tests covering all utility modules +- Run tests before committing changes + +### CI Workflow +The CI workflow is split into three parallel jobs: + +1. **Lint Job** - Runs ESLint on all TypeScript files +2. **Test Job** - Runs tests with coverage and generates reports + - Parses test results and generates GitHub check summaries + - Uploads coverage to Codecov for tracking over time + - Creates test result artifacts +3. **Build Job** - Compiles TypeScript to ensure no build errors + +All jobs must pass before merging pull requests. + +### Coverage Reporting +- Coverage reports generated with every test run +- Integrated with Codecov for tracking coverage trends +- Aim to maintain 100% code coverage for all new features +- Coverage reports available as CI artifacts