npm package: @rabithua/prisma-session-store
Description: A modern Prisma-based session store for Express with TypeScript support and automatic cleanup
Author: rabithua
Latest version: 1.0.0

# @rabithua/prisma-session-store

A modern, TypeScript-first session store for Express.js using Prisma ORM with automatic cleanup functionality.

## Features

- 🚀 **TypeScript Support**: Full TypeScript support with comprehensive type definitions
- 🗄️ **Multi-Database**: Works with all Prisma-supported databases (PostgreSQL, MySQL, SQLite, MongoDB, etc.)
- 🧹 **Auto Cleanup**: Automatic cleanup of expired sessions with configurable intervals
- ⚡ **Performance**: Efficient database operations using Prisma's optimized queries
- 🔧 **Configurable**: Highly configurable with sensible defaults
- 🛡️ **Error Handling**: Robust error handling and graceful degradation
- 📦 **Zero Dependencies**: Only requires Prisma and Express-session as peer dependencies

## Installation

```bash
npm install @rabithua/prisma-session-store
# or
yarn add @rabithua/prisma-session-store
# or
pnpm add @rabithua/prisma-session-store
# or
bun add @rabithua/prisma-session-store
```

## Database Schema

First, add the Session model to your Prisma schema:

```prisma
model Session {
  id        String   @id @default(cuid())
  sid       String   @unique
  data      String
  expiresAt DateTime

  @@map("sessions")
}
```

Then run the migration:

```bash
npx prisma migrate dev
# or for MongoDB
npx prisma db push
```

## Basic Usage

```typescript
import express from 'express';
import session from 'express-session';
import { PrismaClient } from '@prisma/client';
import { PrismaSessionStore } from '@rabithua/prisma-session-store';

const app = express();
const prisma = new PrismaClient();

app.use(session({
  store: new PrismaSessionStore({
    prisma: prisma,
    checkPeriod: 2 * 60 * 1000, // 2 minutes
  }),
  secret: 'your-secret-key',
  resave: false,
  saveUninitialized: false,
  cookie: { 
    maxAge: 1000 * 60 * 60 * 24 * 7 // 1 week
  }
}));

app.listen(3000);
```

## Configuration Options

```typescript
interface PrismaSessionStoreOptions {
  /**
   * Prisma client instance (required)
   */
  prisma: PrismaClient;
  
  /**
   * Cleanup check period in milliseconds
   * @default 120000 (2 minutes)
   */
  checkPeriod?: number;
  
  /**
   * Session table name (if using custom table name)
   * @default 'session'
   */
  tableName?: string;
  
  /**
   * Enable automatic cleanup of expired sessions
   * @default true
   */
  autoCleanup?: boolean;
  
  /**
   * Default session TTL in milliseconds
   * @default 2678400000 (31 days)
   */
  defaultTtl?: number;
}
```

## Advanced Usage

### Custom Table Name

If you're using a different table name in your schema:

```typescript
// In your schema.prisma
model UserSession {
  id        String   @id @default(cuid())
  sid       String   @unique
  data      String
  expiresAt DateTime

  @@map("user_sessions")
}

// In your application
const store = new PrismaSessionStore({
  prisma: prisma,
  tableName: 'userSession', // Use the model name, not the table name
});
```

### Manual Cleanup

```typescript
const store = new PrismaSessionStore({
  prisma: prisma,
  autoCleanup: false, // Disable automatic cleanup
});

// Manual cleanup
const result = await store.cleanup();
console.log(`Cleaned up ${result.deletedCount} expired sessions`);
```

### Stop/Start Cleanup

```typescript
const store = new PrismaSessionStore({ prisma });

// Stop automatic cleanup
store.stopCleanup();

// Restart automatic cleanup
store.startCleanup();
```

## API Reference

### Methods

#### `get(sid, callback)`
Retrieve a session by session ID.

#### `set(sid, session, callback)`
Store or update a session.

#### `destroy(sid, callback)`
Destroy a session.

#### `touch(sid, session, callback)`
Update the expiration time of a session.

#### `all(callback)`
Retrieve all active sessions.

#### `length(callback)`
Get the count of active sessions.

#### `clear(callback)`
Clear all sessions.

#### `cleanup()`
Manually cleanup expired sessions. Returns a promise with the number of deleted sessions.

#### `startCleanup()`
Start automatic cleanup of expired sessions.

#### `stopCleanup()`
Stop automatic cleanup.

## Error Handling

The store handles various error conditions gracefully:

- **Database connection errors**: Passed to Express session callbacks
- **Invalid session data**: Corrupted sessions are ignored during retrieval
- **Missing sessions**: Handled as null/undefined sessions
- **Cleanup errors**: Logged but don't interrupt application flow

## Database Support

This session store works with all databases supported by Prisma:

- PostgreSQL
- MySQL
- SQLite
- MongoDB
- SQL Server
- CockroachDB

## Performance Considerations

- The store uses efficient Prisma queries with proper indexing
- Automatic cleanup runs in the background without blocking operations
- The `sid` field is indexed for fast lookups
- JSON serialization/deserialization is optimized for performance

## Migration from @quixo3/prisma-session-store

This package is designed as a drop-in replacement for `@quixo3/prisma-session-store` with additional features:

```typescript
// Before
import { PrismaSessionStore } from '@quixo3/prisma-session-store';

// After
import { PrismaSessionStore } from '@rabithua/prisma-session-store';

// The API is compatible, just pass the prisma instance
const store = new PrismaSessionStore({
  prisma: prismaClient,
  checkPeriod: 2 * 60 * 1000,
});
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 🐛 [Report bugs](https://github.com/rabithua/prisma-session-store/issues)
- 💡 [Request features](https://github.com/rabithua/prisma-session-store/issues)
- 📖 [Documentation](https://github.com/rabithua/prisma-session-store#readme)

---

Made with ❤️ by [rabithua](https://github.com/rabithua)