Unified Stale Session Package

Overview

The stale session package has been successfully refactored to use a unified approach with the imports/ folder structure. This follows Meteor best practices and provides a single class that works on both client and server.

New Structure

/imports/
  /lib/
    stale-session.ts        # Unified StaleSession class
    types.ts               # TypeScript interfaces and types
    /utils/
      constants.ts         # Package constants
      schemas.ts          # Validation schemas
      settings.ts         # Configuration settings
index.ts                   # Main exports

Key Benefits

✅ Unified Architecture

• Single StaleSession class works on both client and server
• Automatically detects environment using Meteor.isClient/Meteor.isServer
• Shared configuration and logging interface

✅ Meteor Best Practices

• Code placed in imports/ folder for proper tree-shaking
• Only loaded when explicitly imported
• Smaller bundle sizes for both client and server

✅ Environment-Aware Functionality

• Client: Activity detection, heartbeat sending
• Server: Session management, heartbeat collection, user logout
• Methods throw appropriate errors when called in wrong environment

✅ Backward Compatibility

• Legacy StaleSessionClient and StaleSessionServer exports available
• Existing code should work with minimal changes
• Same configuration options and method signatures

Usage

Simple Usage (Recommended)

1import { StaleSession } from 'meteor/bboyredstar:stale-session';
2
3const staleSession = new StaleSession({
4  heartbeatIntervalMs: 180000, // 3 minutes
5  inactiveTimeoutMs: 1800000,  // 30 minutes
6  forceLogout: true
7});
8
9await staleSession.run(); // Works on both client and server

Legacy Usage (Still Supported)

1import { StaleSessionClient, StaleSessionServer } from 'meteor/bboyredstar:stale-session';
2
3// Both are aliases to the same unified class
4const client = new StaleSessionClient();
5const server = new StaleSessionServer();

Configuration Options

All configuration is now optional with sensible defaults:

1interface StaleSessionConfig {
2  heartbeatIntervalMs: number;      // Default: 180000 (3 min)
3  inactiveTimeoutMs: number;        // Default: 1800000 (30 min)
4  forceLogout: boolean;             // Default: false
5  heartbeatCollectionName: string;  // Default: "heartbeat"
6  activityEvents?: string;          // Default: "mousemove click keydown"
7}

Environment-Specific Methods

Client Methods

• isActivityDetected(): Check if user activity was detected
• markActivityDetected(): Manually mark activity

Server Methods

• getCollection(): Access the heartbeat MongoDB collection

Shared Methods

• run(): Start the stale session monitoring
• getHeartbeatInterval(): Get heartbeat interval setting
• getInactiveTimeout(): Get inactive timeout setting
• isForceLogoutEnabled(): Check if force logout is enabled
• getHeartbeatCollectionName(): Get collection name
• getActivityEvents(): Get activity events string

Error Handling

The unified class includes comprehensive error handling:

• Configuration validation using schemas
• Graceful fallbacks for missing dependencies
• Clear error messages when methods are called in wrong environment
• Enhanced logging throughout the lifecycle

Migration Guide

From Separate Classes

If you were using separate client and server classes:

Before:

1// Client code
2import { StaleSessionClient } from './client/stale-session-client';
3const client = new StaleSessionClient(logger);
4client.run();
5
6// Server code  
7import { StaleSessionServer } from './server/stale-session-server';
8const server = new StaleSessionServer(logger);
9await server.run();

After:

1// Works everywhere
2import { StaleSession } from 'meteor/bboyredstar:stale-session';
3const staleSession = new StaleSession(config, logger);
4await staleSession.run();

Configuration Changes

Configuration is now unified and more flexible:

Before:

1// Fixed settings from Meteor.settings
2const client = new StaleSessionClient(logger);

After:

1// Configurable with defaults
2const staleSession = new StaleSession({
3  heartbeatIntervalMs: 120000,  // Override default
4  forceLogout: true
5}, logger);

Benefits Summary

1. Simplified API: One class instead of two
2. Better Performance: Tree-shaking and on-demand loading
3. Type Safety: Comprehensive TypeScript support
4. Flexibility: Configurable options with sensible defaults
5. Maintainability: Single codebase for both environments
6. Error Handling: Improved error handling and logging
7. Future-Proof: Easier to extend and modify

The refactored package maintains full backward compatibility while providing a modern, unified approach to stale session management in Meteor applications.