faye-redis-ng 1.0.2 → 1.1.0

package/NPM_PUBLISH.md

@@ -1,358 +0,0 @@
-# NPM Publishing Guide for faye-redis-ng
-
-This guide will help you publish `faye-redis-ng` to npm.
-
-## 🤖 Automated Publishing with Trusted Publishing (Recommended)
-
-This project uses **GitHub Actions** with **Trusted Publishing (OIDC)** - the modern, secure way to publish to npm. No tokens needed!
-
-### 🔒 Why Trusted Publishing?
-
-**Traditional method** ❌:
-- Create npm token
-- Store in GitHub Secrets
-- Risk of token leakage
-- Manual token rotation
-
-**Trusted Publishing** ✅:
-- Zero tokens to manage
-- GitHub authenticates directly with npm
-- More secure (OIDC protocol)
-- Recommended by npm
-
-### Quick Start
-
-**Step 1**: First manual publish (once)
-```bash
-npm login
-npm publish --access public
-```
-
-**Step 2**: Configure on npm
-1. Go to https://www.npmjs.com/package/faye-redis-ng/settings
-2. Publishing access → Add trusted publisher
-3. Provider: **GitHub Actions**
-4. Repository: **YOUR-USERNAME/faye-redis-ng**
-5. Workflow: **publish.yml**
-
-**Step 3**: Push tags
-```bash
-git tag v1.0.1 && git push origin v1.0.1
-```
-
-**Done!** 🎉 Fully automated, zero secrets.
-
-**See `.github/SETUP.md` for detailed setup instructions.**
-
----
-
-## 📦 Manual Publishing (Alternative)
-
-If you prefer manual control or need to publish without automation:
-
-## Pre-Publishing Checklist
-
-### 1. Verify Package Information
-
-- ✅ Package name: `faye-redis-ng`
-- ✅ Version: `1.0.0` (starting fresh for NG version)
-- ✅ Description updated
-- ✅ Keywords added for discoverability
-- ✅ License: MIT (same as original)
-- ✅ Repository URL (update when you create your fork)
-
-### 2. Prepare Your Repository
-
-**Important**: Update the repository URL in `package.json` to point to YOUR fork:
-
-```json
-{
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/YOUR-USERNAME/faye-redis-ng.git"
-  },
-  "homepage": "https://github.com/YOUR-USERNAME/faye-redis-ng",
-  "bugs": "https://github.com/YOUR-USERNAME/faye-redis-ng/issues"
-}
-```
-
-### 3. Files to Include/Exclude
-
-Create or update `.npmignore`:
-
-```
-# Development files
-spec/
-vendor/
-test-*.js
-.git/
-.gitmodules
-*.rdb
-
-# Documentation (keep these)
-!README.md
-!CLAUDE.md
-!REFACTORING.md
-!CHANGELOG.md
-!LICENSE
-```
-
-Or use `files` field in package.json (recommended):
-
-```json
-{
-  "files": [
-    "faye-redis.js",
-    "README.md",
-    "CLAUDE.md",
-    "REFACTORING.md",
-    "LICENSE"
-  ]
-}
-```
-
-### 4. Create Essential Files
-
-**LICENSE** (if not exists):
-```
-MIT License
-
-Copyright (c) 2011-2013 James Coglan (original faye-redis)
-Copyright (c) 2026-present Community Contributors (faye-redis-ng)
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
-**CHANGELOG.md**:
-```markdown
-# Changelog
-
-All notable changes to faye-redis-ng will be documented in this file.
-
-## [1.0.0] - 2026-01-07
-
-### Added
-- Initial release of faye-redis-ng (Next Generation fork)
-- Redis v4 support with Promise-based API
-- Automatic reconnection with exponential backoff
-- ES6+ class syntax and modern JavaScript features
-- Comprehensive error handling and logging
-- Auto re-subscribe after reconnection
-- Better documentation and examples
-
-### Changed
-- Upgraded from callback-based to async/await internally
-- Updated from prototype-based to ES6 class
-- Node.js requirement: >=14.0.0 (was >=0.4.0)
-- All Redis commands updated to v4 API
-
-### Improved
-- Production-ready reconnection handling
-- Better error messages and debugging
-- Updated dependencies to latest versions
-- Modernized codebase while maintaining backward compatibility
-
-### Migration
-- Drop-in replacement for original faye-redis
-- No breaking changes to public API
-- Simply replace `require('faye-redis')` with `require('faye-redis-ng')`
-
-## Original faye-redis
-
-This project is a modernized fork of [faye-redis](https://github.com/faye/faye-redis-node) by James Coglan.
-```
-
-## Publishing Steps
-
-### Step 1: Create npm Account (if you don't have one)
-
-```bash
-npm adduser
-# or
-npm login
-```
-
-### Step 2: Test Package Locally
-
-```bash
-# Test installation locally
-npm pack
-
-# This creates faye-redis-ng-1.0.0.tgz
-# Test it in another project:
-cd /path/to/test-project
-npm install /path/to/faye-redis-ng-1.0.0.tgz
-```
-
-### Step 3: Verify Package Contents
-
-```bash
-# Check what will be published
-npm publish --dry-run
-
-# Review the output carefully
-```
-
-### Step 4: Run Final Checks
-
-```bash
-# Lint package.json
-npm install -g npm-package-json-lint
-npmPkgJsonLint .
-
-# Or manually verify:
-# - All dependencies are correct versions
-# - No sensitive information in any files
-# - README is complete
-# - Version number is correct
-```
-
-### Step 5: Publish to npm
-
-```bash
-# Publish to npm (public)
-npm publish --access public
-
-# If you want to test first, publish to a scoped package:
-# npm publish --access public --tag beta
-```
-
-### Step 6: Verify Publication
-
-```bash
-# Check on npm
-npm view faye-redis-ng
-
-# Install and test
-npm install faye-redis-ng
-```
-
-## Post-Publishing
-
-### 1. Create Git Tag
-
-```bash
-git tag v1.0.0
-git push origin v1.0.0
-```
-
-### 2. Create GitHub Release
-
-Go to your GitHub repository and create a release:
-- Tag: `v1.0.0`
-- Title: `v1.0.0 - Initial Release`
-- Description: Copy from CHANGELOG.md
-
-### 3. Update Documentation
-
-- Add badges to README.md with actual npm package link
-- Update homepage URL if needed
-
-### 4. Announce
-
-Consider announcing on:
-- Twitter/X
-- Reddit (r/node, r/javascript)
-- Hacker News
-- Dev.to
-
-## Version Management
-
-### Semantic Versioning
-
-Follow [semver](https://semver.org/):
-
-- **MAJOR**: Breaking changes (2.0.0)
-- **MINOR**: New features, backward compatible (1.1.0)
-- **PATCH**: Bug fixes, backward compatible (1.0.1)
-
-### Publishing Updates
-
-```bash
-# For patches (bug fixes)
-npm version patch
-npm publish
-
-# For minor (new features)
-npm version minor
-npm publish
-
-# For major (breaking changes)
-npm version major
-npm publish
-```
-
-## Troubleshooting
-
-### Package Name Already Taken
-
-If `faye-redis-ng` is taken, consider:
-- `@yourscope/faye-redis-ng`
-- `faye-redis-modern`
-- `faye-redis-v4`
-- `faye-redis-next`
-
-### Can't Publish
-
-Common issues:
-1. **Not logged in**: Run `npm login`
-2. **Name conflict**: Choose different name
-3. **Version exists**: Bump version with `npm version patch`
-4. **Email not verified**: Check npm email verification
-
-## Security
-
-### Before Publishing
-
-- ✅ No API keys or secrets in code
-- ✅ No .env files included
-- ✅ Dependencies are from trusted sources
-- ✅ Run `npm audit` and fix vulnerabilities
-
-```bash
-npm audit
-npm audit fix
-```
-
-### After Publishing
-
-Set up:
-- GitHub security alerts
-- Dependabot
-- npm 2FA for publishing
-
-## Maintenance
-
-### Keeping Updated
-
-1. Monitor dependencies: `npm outdated`
-2. Update dependencies regularly
-3. Test before publishing updates
-4. Keep CHANGELOG.md updated
-5. Respond to issues and PRs
-
-## Questions?
-
-- npm documentation: https://docs.npmjs.com/
-- Semantic versioning: https://semver.org/
-- Package.json docs: https://docs.npmjs.com/cli/v10/configuring-npm/package-json
-
----
-
-**Good luck with your first publish! 🚀**

package/REFACTORING.md

@@ -1,215 +0,0 @@
-# Modernization & Refactoring Summary
-
-This document summarizes the modernization work performed on the faye-redis codebase in January 2026.
-
-## Overview
-
-The codebase was originally written for Node.js 0.4+ and used outdated patterns and dependencies. It has been fully modernized while maintaining backward compatibility with the Faye engine interface.
-
-## Changes Made
-
-### 1. Dependencies Upgraded
-
-**package.json** changes:
-- `redis`: `""` → `"^4.7.0"` (major upgrade to Promise-based API)
-- `jstest`: `""` → `"^1.0.5"` (version pinned)
-- Node.js requirement: `">=0.4.0"` → `">=22.0.0"` (LTS)
-
-**Other fixes**:
-- `.gitmodules`: Changed from `git://` to `https://` protocol (fixes firewall issues)
-
-### 2. Code Modernization
-
-**faye-redis.js** - Complete rewrite with modern JavaScript:
-
-#### Before (Old Style):
-```javascript
-var Engine = function(server, options) {
-  this._server = server;
-  this._options = options || {};
-  var redis = require('redis');
-  var host = this._options.host || this.DEFAULT_HOST;
-  // ... prototype-based class
-};
-
-Engine.prototype = {
-  DEFAULT_HOST: 'localhost',
-  createClient: function(callback, context) {
-    var self = this;
-    this._redis.zadd(this._ns + '/clients', 0, clientId, function(error, added) {
-      // callback hell
-    });
-  }
-};
-```
-
-#### After (Modern Style):
-```javascript
-const redis = require('redis');
-
-class Engine {
-  constructor(server, options = {}) {
-    this._server = server;
-    this._options = options;
-    // ES6 class with async initialization
-  }
-
-  async _initializeClients() {
-    const clientConfig = {
-      database: db,
-      ...(auth && { password: auth }),
-    };
-    this._redis = redis.createClient(clientConfig);
-    await this._redis.connect();
-  }
-
-  createClient(callback, context) {
-    this._waitForInit().then(async () => {
-      const added = await this._redis.zAdd(this._ns + '/clients', {
-        score: 0,
-        value: clientId
-      }, { NX: true });
-      // Clean async/await internally, callback externally
-    });
-  }
-}
-
-Engine.prototype.DEFAULT_HOST = 'localhost';
-```
-
-#### Specific Improvements:
-- ✅ `var` → `const`/`let` throughout
-- ✅ Prototype-based class → ES6 `class`
-- ✅ Callbacks → async/await (internal)
-- ✅ Arrow functions for cleaner code
-- ✅ Spread operators for configuration
-- ✅ Async initialization pattern
-
-### 3. Redis v4 API Migration
-
-Major API changes from old callback-based redis to modern Promise-based redis v4:
-
-| Old API (v0.x) | New API (v4.x) |
-|----------------|----------------|
-| `redis.createClient(port, host, options)` | `redis.createClient({ socket: { host, port }, ... })` |
-| `client.auth(password)` | Config: `{ password: ... }` |
-| `client.zadd(key, score, value, cb)` | `await client.zAdd(key, { score, value })` |
-| `client.zscore(key, value, cb)` | `await client.zScore(key, value)` |
-| `client.smembers(key, cb)` | `await client.sMembers(key)` |
-| `client.getset(key, val, cb)` | `await client.set(key, val, { GET: true })` |
-| `client.end()` | `await client.quit()` |
-| No connect needed | `await client.connect()` required |
-
-### 4. Test Files Updated
-
-**spec/faye_redis_spec.js**:
-- Updated to use `const` instead of `var`
-- Migrated Redis client creation to v4 API
-- Changed `.auth()` to config-based authentication
-- Updated `.flushall(callback)` → `.flushAll()` (Promise-based)
-- Updated `.end()` → `.quit()`
-
-### 5. Architecture Improvements
-
-**New async initialization pattern**:
-- Redis clients initialize asynchronously in constructor
-- `_waitForInit()` method ensures clients are ready before operations
-- Maintains callback-based external API for Faye compatibility
-- Internal operations use clean async/await
-
-**Error handling & Reconnection**:
-- Added try-catch error logging for all async operations
-- Graceful handling of connection errors
-- **Automatic reconnection**: Exponential backoff strategy with max 20 retries
-- **Re-subscribe on reconnect**: Pub/sub channels automatically re-subscribed
-- **Error events**: Connection errors triggered to Faye server
-- **Connection state tracking**: `_initialized` flag prevents operations during reconnection
-
-## Backward Compatibility
-
-✅ **External API unchanged** - All public methods maintain the same callback-based signatures expected by Faye
-
-✅ **Configuration compatible** - All existing configuration options work the same way
-
-✅ **Redis data model unchanged** - Same keys, data structures, and protocols
-
-## Testing Status
-
-✅ **Syntax validation passed** - Code loads without errors
-✅ **Module structure verified** - ES6 class exports correctly
-✅ **API compatibility maintained** - Public interface unchanged
-
-⚠️ **Full integration tests require**:
-1. Redis server running (not available in current environment)
-2. Faye vendor submodule build (requires fixing old build tool compatibility with Node.js 24)
-
-## Files Modified
-
-1. `package.json` - Dependencies and Node version updated
-2. `faye-redis.js` - Complete modernization to ES6+ and Redis v4
-3. `spec/faye_redis_spec.js` - Test updates for Redis v4 API
-4. `.gitmodules` - Protocol change to HTTPS
-5. `CLAUDE.md` - Documentation updated with modernization notes
-6. `REFACTORING.md` - This summary (new file)
-7. `test-syntax.js` - Syntax validation script (new file)
-
-## Migration Guide for Users
-
-If you're upgrading from the old version:
-
-1. **Update Node.js**: Ensure you have Node.js >= 22.0.0 (LTS)
-2. **Install dependencies**: Run `npm install` to get Redis v4
-3. **No code changes needed**: Your Faye configuration remains the same
-4. **Redis v4 benefits**: Better performance, modern Promise API, improved error handling
-
-## Reconnection Mechanism (New Feature)
-
-The modernized code includes production-ready reconnection handling that was missing in the original:
-
-### How It Works
-
-```javascript
-// Reconnection strategy with exponential backoff
-_reconnectStrategy(retries) {
-  if (retries > 20) {
-    return new Error('Max reconnection attempts reached');
-  }
-  const delay = Math.min(retries * 100, 10000);
-  return delay; // 100ms, 200ms, 300ms ... up to 10s
-}
-```
-
-### Event Handlers
-
-1. **`error` event**: Logs errors and notifies Faye server
-2. **`reconnecting` event**: Sets `_initialized = false` to pause operations
-3. **`ready` event**: Re-subscribes to pub/sub channels and sets `_initialized = true`
-
-### Protection During Reconnection
-
-All operations use `_waitForInit()` to ensure Redis is ready:
-```javascript
-async _waitForInit() {
-  while (!this._initialized) {
-    await new Promise(resolve => setTimeout(resolve, 10));
-  }
-}
-```
-
-This prevents operations from failing during reconnection and automatically resumes when connection is restored.
-
-## Next Steps (Optional Future Work)
-
-- Add TypeScript definitions for better IDE support
-- Replace jstest with modern testing framework (Jest/Mocha)
-- Add ESLint configuration for code quality
-- Add CI/CD with GitHub Actions
-- Update Faye vendor submodule to newer version (if available)
-- Add metrics/monitoring for reconnection events
-
----
-
-**Refactored by**: Claude Code
-**Date**: January 2026
-**Redis version**: 4.7.0
-**Node.js target**: >= 22.0.0 (LTS)