From e535bf33c76e785536c5b60209967c97c9f33d9b Mon Sep 17 00:00:00 2001 From: Scott Lusk Date: Tue, 21 Oct 2025 17:27:41 -0400 Subject: [PATCH 1/9] update ignore to only ship necessary files --- .npmignore | 56 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 16 deletions(-) diff --git a/.npmignore b/.npmignore index 36ab5cc..be9991c 100644 --- a/.npmignore +++ b/.npmignore @@ -1,39 +1,63 @@ -# Source files +# Source files (already compiled to dist/) src/ +__tests__/ +samples/ +docs/ + +# Build artifacts +coverage/ +*.tsbuildinfo +.turbo/ + +# Development files +.github/ +.husky/ +.vscode/ +.idea/ +*.log *.test.ts *.spec.ts +*.test.js +*.spec.js +*.test.d.ts +*.spec.d.ts # Config files -tsconfig.json -vitest.config.ts -eslint.config.js +.nvmrc .prettierrc .prettierignore .editorconfig -.nvmrc +eslint.config.js +vitest.config.ts +tsconfig.json -# CI/CD -.github/ +# Git +.git/ .gitignore -.husky/ +.gitattributes -# Development -coverage/ +# Node modules node_modules/ -.vscode/ -.idea/ + +# Temp directories +temp/ # Logs -*.log npm-debug.log* yarn-debug.log* yarn-error.log* pnpm-debug.log* -# Misc -.DS_Store +# Environment files .env .env.local .env.*.local -# Documentation +# OS files +.DS_Store + +# Documentation (keep only essential) +*.md +!README.md +!LICENSE +!CHANGELOG.md From ad45095a16984ad7c953c1307fd5337e2d6ffdf3 Mon Sep 17 00:00:00 2001 From: Scott Lusk Date: Tue, 21 Oct 2025 17:27:52 -0400 Subject: [PATCH 2/9] add release helper script --- package.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/package.json b/package.json index 306cf5e..29f5168 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,8 @@ "typecheck": "tsc --noEmit", "ci": "pnpm run typecheck && pnpm run lint && pnpm run format:check && pnpm run build && pnpm run test", "prepare": "husky", - "prepublishOnly": "pnpm run ci" + "prepublishOnly": "pnpm run ci", + "release:check": "pnpm run ci && echo '\n✅ Ready for release! Next steps:\n1. Update CHANGELOG.md\n2. Run: npm version [patch|minor|major]\n3. Run: git push && git push --tags\n4. Create GitHub release'" }, "keywords": [ "export", From 12c3a43111e8d8906f2826d8411519373c7f1c16 Mon Sep 17 00:00:00 2001 From: Scott Lusk Date: Tue, 21 Oct 2025 17:28:01 -0400 Subject: [PATCH 3/9] update to include provenance --- .github/workflows/publish.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 1afb127..9abe2ce 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -2,6 +2,7 @@ name: Publish to npm permissions: contents: read + id-token: write # Required for provenance on: release: @@ -32,7 +33,7 @@ jobs: run: pnpm run ci - name: Publish to npm - run: pnpm publish --no-git-checks + run: pnpm publish --no-git-checks --provenance env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} From 86453d0a538c2a693e6e7487faaa5e3fe9c41c72 Mon Sep 17 00:00:00 2001 From: Scott Lusk Date: Tue, 21 Oct 2025 17:28:08 -0400 Subject: [PATCH 4/9] add initial changelog --- CHANGELOG.md | 86 +++++++++++++++++++++++++++++++++++----------------- 1 file changed, 58 insertions(+), 28 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7177850..d5ac212 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,40 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.0.6] - 2025-10-21 + ### Added -- Initial project setup with TypeScript, pnpm, and ES modules -- TypeScript configuration with strict mode enabled -- Vitest for testing with code coverage -- ESLint v9 with flat config format -- Prettier for code formatting -- GitHub Actions CI pipeline running on Node.js 18.x, 20.x, and 22.x -- Pre-commit hooks with Husky and lint-staged -- Dependabot configuration for automated dependency updates -- Comprehensive project documentation -- Sample `greet` and `add` functions with full test coverage -- VSCode workspace settings for optimal developer experience -- EditorConfig for cross-editor consistency -- `.nvmrc` file specifying Node.js 22 +- **Initial public release** of `@scottluskcis/outport` +- **Fluent Builder API** - Intuitive, chainable configuration for data exports +- **CSV Export Support** + - Configurable delimiters (comma, tab, semicolon, pipe) + - Custom header labels + - UTF-8 BOM support for Excel compatibility + - Automatic field escaping and quoting + - Header management and validation +- **JSON Export Support** + - Array and object output formats + - Pretty printing with configurable indentation + - Streaming JSON array output +- **Async Generator Streaming** - Efficiently handle large datasets + - Memory-efficient processing of millions of records + - Automatic batching for optimal performance + - Configurable batch sizes +- **Lifecycle Hooks System** + - `onBeforeWrite` - Transform or filter data before export + - `onProgress` - Track export progress in real-time + - `onAfterWrite` - Post-processing after write completes + - `onError` - Centralized error handling + - `onComplete` - Final success/failure notifications +- **Type-Safe API** - Full TypeScript support with strict typing + - Generic type parameters for data records + - Comprehensive type definitions + - Type inference throughout the API +- **High Performance** + - Automatic batching for large datasets + - Memory optimization for streaming + - Efficient file I/O operations +- **Well-Tested Codebase** + - 170+ test cases across all components + - 80%+ code coverage + - Comprehensive unit and integration tests +- **Complete Documentation** + - Builder API guide with advanced patterns + - CSV writer examples and best practices + - JSON writer usage patterns + - Type safety examples + - Sample code for common use cases +- **GitHub Actions CI/CD Pipeline** + - Automated testing on Node.js 18.x, 20.x, and 22.x + - Automated npm publishing on release + - Code coverage reporting + - Automated dependency updates via Dependabot +- **Development Tools** + - ESLint v9 with flat config + - Prettier code formatting + - Husky pre-commit hooks + - Vitest for testing + - TypeScript strict mode ### Changed -- N/A - -### Deprecated - -- N/A - -### Removed - -- N/A - -### Fixed - -- N/A +- N/A (initial release) ### Security -- N/A +- Added npm provenance for supply chain security +- Implemented granular npm access tokens -[unreleased]: https://github.com/scottluskcis/outport/commits/init-setup +[unreleased]: https://github.com/scottluskcis/outport/compare/v0.0.6...HEAD +[0.0.6]: https://github.com/scottluskcis/outport/releases/tag/v0.0.6 From 39bf83e8a666a0ebdb1dc3dd3d3b91d78ddc1f7f Mon Sep 17 00:00:00 2001 From: Scott Lusk Date: Tue, 21 Oct 2025 17:28:36 -0400 Subject: [PATCH 5/9] add notes for release process --- docs/release-process.md | 361 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 361 insertions(+) create mode 100644 docs/release-process.md diff --git a/docs/release-process.md b/docs/release-process.md new file mode 100644 index 0000000..9982bdb --- /dev/null +++ b/docs/release-process.md @@ -0,0 +1,361 @@ +# Release Process + +This document outlines the standardized release process for `@scottluskcis/outport`. + +## Pre-Release Checklist + +Before creating a release, ensure all of the following are complete: + +### 1. Ensure All Changes Are Merged + +```bash +git checkout main +git pull origin main +``` + +### 2. Run Release Check + +This validates that your code is ready for release: + +```bash +pnpm run release:check +``` + +This command runs: + +- ✅ Type checking (`typecheck`) +- ✅ Linting (`lint`) +- ✅ Format checking (`format:check`) +- ✅ Build process (`build`) +- ✅ All tests (`test`) + +**All checks must pass before proceeding.** + +### 3. Update CHANGELOG.md + +Follow the [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format: + +1. **Move items from `[Unreleased]` to new version section** +2. **Add the version number and date**: + ```markdown + ## [X.Y.Z] - YYYY-MM-DD + ``` +3. **Organize changes by category**: + - **Added** - New features + - **Changed** - Changes in existing functionality + - **Deprecated** - Soon-to-be removed features + - **Removed** - Removed features + - **Fixed** - Bug fixes + - **Security** - Security improvements +4. **Update comparison links at bottom of file**: + ```markdown + [unreleased]: https://github.com/scottluskcis/outport/compare/vX.Y.Z...HEAD + [x.y.z]: https://github.com/scottluskcis/outport/compare/vX.Y.Z-1...vX.Y.Z + ``` + +Example: + +```markdown +## [Unreleased] + +## [0.0.7] - 2025-10-22 + +### Added + +- New feature X +- Improvement to feature Y + +### Fixed + +- Bug fix for issue #123 + +[unreleased]: https://github.com/scottluskcis/outport/compare/v0.0.7...HEAD +[0.0.7]: https://github.com/scottluskcis/outport/compare/v0.0.6...v0.0.7 +``` + +### 4. Commit Changelog + +```bash +git add CHANGELOG.md +git commit -m "docs: update changelog for vX.Y.Z" +git push origin main +``` + +## Release Steps + +### 1. Bump Version + +Use npm's built-in version command to update [`package.json`](package.json) and create a git tag: + +```bash +# For bug fixes (0.0.6 → 0.0.7) +npm version patch + +# For new features (0.0.6 → 0.1.0) +npm version minor + +# For breaking changes (0.0.6 → 1.0.0) +npm version major +``` + +This command: + +- Updates the `version` field in [`package.json`](package.json) +- Creates a git commit with the message "X.Y.Z" +- Creates a git tag `vX.Y.Z` + +### 2. Push Changes with Tags + +```bash +git push && git push --tags +``` + +This pushes: + +- The version bump commit +- The new version tag + +### 3. Create GitHub Release + +1. **Navigate to Releases**: + - Go to: https://github.com/scottluskcis/outport/releases/new + +2. **Select the Tag**: + - Choose the tag you just created (e.g., `v0.0.7`) + +3. **Set Release Title**: + - Format: `vX.Y.Z` (e.g., `v0.0.7`) + +4. **Add Release Description**: + - Copy the relevant section from [`CHANGELOG.md`](CHANGELOG.md) + - Format it nicely for GitHub (supports Markdown) + +5. **Publish Release**: + - Click **"Publish release"** + - This triggers the automated npm publishing workflow + +### 4. Monitor Workflow + +1. **Watch the GitHub Action**: + - Go to: https://github.com/scottluskcis/outport/actions + - Look for "Publish to npm" workflow + - Ensure it completes successfully + +2. **Check for Errors**: + - Green checkmark ✅ = Success + - Red X ❌ = Failure (check logs) + +### 5. Verify Publication + +After the workflow completes: + +1. **Check npm Registry**: + + ```bash + npm view @scottluskcis/outport + ``` + + Should show the new version. + +2. **Visit npm Package Page**: + - Go to: https://www.npmjs.com/package/@scottluskcis/outport + - Verify the new version is listed + - Check for the provenance badge (🔒 verified) + +3. **Test Installation**: + + ```bash + npm install @scottluskcis/outport@latest + ``` + + Or in a test project: + + ```bash + mkdir test-install && cd test-install + npm init -y + npm install @scottluskcis/outport + node -e "console.log(require('@scottluskcis/outport'))" + ``` + +## Post-Release + +### 1. Verify Package Contents + +Check what was actually published: + +```bash +npm pack @scottluskcis/outport@latest --dry-run +``` + +This shows the files included in the published package. + +### 2. Update Documentation (if needed) + +If the release includes API changes: + +- Update README.md examples +- Update documentation in `docs/` folder +- Update JSDoc comments if needed + +### 3. Announce the Release + +Consider announcing on: + +- GitHub Discussions +- Twitter/X +- Dev.to or other developer communities +- Your blog + +## Semantic Versioning Guide + +Follow [Semantic Versioning 2.0.0](https://semver.org/): + +### MAJOR Version (X.0.0) + +Increment when you make **incompatible API changes**: + +- Removing public APIs +- Changing function signatures +- Breaking existing functionality + +**Example**: Removing `outport().toFile()` method + +### MINOR Version (0.X.0) + +Increment when you add **functionality in a backward-compatible manner**: + +- Adding new features +- Adding new methods +- Adding optional parameters + +**Example**: Adding XML export support + +### PATCH Version (0.0.X) + +Increment when you make **backward-compatible bug fixes**: + +- Fixing bugs +- Performance improvements +- Documentation updates + +**Example**: Fixing CSV escaping issue + +## Troubleshooting + +### Release Check Fails + +**Problem**: `pnpm run release:check` shows errors + +**Solution**: + +1. Fix the errors shown +2. Commit and push fixes +3. Run `release:check` again + +### GitHub Workflow Fails + +**Problem**: "Publish to npm" workflow fails in Actions + +**Common Causes**: + +1. **Authentication Error**: + - Verify `NPM_TOKEN` secret is set correctly + - Ensure token has "Read and write" permissions for `@scottluskcis/outport` + - Check token hasn't expired + +2. **Version Already Published**: + - npm doesn't allow republishing the same version + - Bump to a new version + +3. **CI Checks Fail**: + - Tests failing + - Linting errors + - Format check failures + - Fix locally and re-release + +### Wrong Version Published + +**Problem**: Published wrong version number + +**Solution (within 72 hours)**: + +```bash +# Unpublish the incorrect version (use sparingly!) +npm unpublish @scottluskcis/outport@X.Y.Z + +# Publish the correct version +npm version patch +git push && git push --tags +# Create new GitHub release +``` + +**⚠️ Warning**: Unpublishing is discouraged. Consider publishing a corrected version instead. + +### Need to Rollback + +**Problem**: Critical bug in latest release + +**Recommended Approach**: + +1. **Publish a fixed patch version** (preferred): + + ```bash + # Fix the bug + npm version patch + git push && git push --tags + # Create new release + ``` + +2. **Deprecate the broken version**: + ```bash + npm deprecate @scottluskcis/outport@X.Y.Z "Critical bug, please upgrade to X.Y.Z+1" + ``` + +## Emergency Contacts + +- **npm Support**: https://www.npmjs.com/support +- **GitHub Support**: https://support.github.com/ + +## Helpful Commands + +```bash +# Check what would be published +npm pack --dry-run + +# View package info on npm +npm view @scottluskcis/outport + +# View specific version +npm view @scottluskcis/outport@X.Y.Z + +# List all published versions +npm view @scottluskcis/outport versions + +# Check latest version +npm view @scottluskcis/outport version + +# Test package in a temporary directory +mkdir /tmp/test-outport && cd /tmp/test-outport +npm init -y +npm install @scottluskcis/outport +``` + +## Release Frequency + +Recommended cadence: + +- **Patch releases**: As needed for bug fixes +- **Minor releases**: When new features are ready (every 2-4 weeks) +- **Major releases**: Only when necessary (breaking changes) + +## Conclusion + +Following this process ensures: + +- ✅ Quality releases (all checks pass) +- ✅ Proper versioning (semantic versioning) +- ✅ Complete documentation (changelog) +- ✅ Automated publishing (GitHub Actions) +- ✅ Verified packages (npm provenance) + +Happy releasing! 🚀 From 056c036353e8d160af329adc37e09badac11f686 Mon Sep 17 00:00:00 2001 From: Scott Lusk Date: Tue, 21 Oct 2025 17:31:04 -0400 Subject: [PATCH 6/9] Update docs/release-process.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/release-process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release-process.md b/docs/release-process.md index 9982bdb..55af58d 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -85,7 +85,7 @@ git push origin main ### 1. Bump Version -Use npm's built-in version command to update [`package.json`](package.json) and create a git tag: +Use npm's built-in version command to update [`package.json`](../package.json) and create a git tag: ```bash # For bug fixes (0.0.6 → 0.0.7) From 774515bd60eba8d0f66a21f39f3ccc253b22e38e Mon Sep 17 00:00:00 2001 From: Scott Lusk Date: Tue, 21 Oct 2025 17:31:11 -0400 Subject: [PATCH 7/9] Update docs/release-process.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/release-process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release-process.md b/docs/release-process.md index 55af58d..c1e085c 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -127,7 +127,7 @@ This pushes: - Format: `vX.Y.Z` (e.g., `v0.0.7`) 4. **Add Release Description**: - - Copy the relevant section from [`CHANGELOG.md`](CHANGELOG.md) + - Copy the relevant section from [`CHANGELOG.md`](../CHANGELOG.md) - Format it nicely for GitHub (supports Markdown) 5. **Publish Release**: From 01162eeb6796cf14826a2926f10af609df58b806 Mon Sep 17 00:00:00 2001 From: Scott Lusk Date: Tue, 21 Oct 2025 17:31:53 -0400 Subject: [PATCH 8/9] fix --- docs/release-process.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/release-process.md b/docs/release-process.md index c1e085c..e9cf7f8 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -100,7 +100,7 @@ npm version major This command: -- Updates the `version` field in [`package.json`](package.json) +- Updates the `version` field in [`package.json`](../package.json) - Creates a git commit with the message "X.Y.Z" - Creates a git tag `vX.Y.Z` From 70f96c41a95be6389c5d08afcf8fec6b5ffffd8e Mon Sep 17 00:00:00 2001 From: Scott Lusk Date: Tue, 21 Oct 2025 17:32:11 -0400 Subject: [PATCH 9/9] Update package.json Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 29f5168..badb557 100644 --- a/package.json +++ b/package.json @@ -30,7 +30,7 @@ "ci": "pnpm run typecheck && pnpm run lint && pnpm run format:check && pnpm run build && pnpm run test", "prepare": "husky", "prepublishOnly": "pnpm run ci", - "release:check": "pnpm run ci && echo '\n✅ Ready for release! Next steps:\n1. Update CHANGELOG.md\n2. Run: npm version [patch|minor|major]\n3. Run: git push && git push --tags\n4. Create GitHub release'" + "release:check": "pnpm run ci && echo '' && echo '✅ Ready for release! Next steps:' && echo '1. Update CHANGELOG.md' && echo '2. Run: npm version [patch|minor|major]' && echo '3. Run: git push && git push --tags' && echo '4. Create GitHub release'" }, "keywords": [ "export",