@jazim/test 2.0.3 → 2.0.5

package/README.md

@@ -1,143 +1,488 @@
-# TypeORM Adapter for Better-Auth
+# @jazim/typeorm-better-auth
 
-A TypeORM database adapter for [Better-Auth](https://github.com/better-auth/better-auth), providing seamless authentication with TypeORM.
+A TypeORM adapter for [Better Auth](https://www.better-auth.com/) that provides seamless integration between TypeORM and Better Auth's authentication system.
+
+[![npm version](https://img.shields.io/npm/v/@jazim/typeorm-better-auth.svg)](https://www.npmjs.com/package/@jazim/typeorm-better-auth)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-- ✅ Full TypeORM integration
-- ✅ TypeScript support with full type safety
-- ✅ Schema generation via Better-Auth CLI
-- ✅ Configurable table names (singular/plural)
-- ✅ Transaction support
-- ✅ Supports all major databases (PostgreSQL, MySQL, SQLite, SQL Server, Oracle, MongoDB)
+- 🔌 **Seamless Integration** - Drop-in TypeORM adapter for Better Auth
+- 🗄️ **Multi-Database Support** - PostgreSQL, MySQL, and SQLite
+- 🔄 **Auto Generation** - Automatic entity and migration generation
+- 🎯 **Type Safe** - Full TypeScript support
+- 🛠️ **Customizable** - Configure entity names and paths
+- 💪 **Transaction Support** - Built-in transaction handling
+- 🔍 **Advanced Queries** - Support for complex where clauses and operators
 
 ## Installation
 
 ```bash
-npm install typeorm-adapter-betterauth typeorm better-auth
-# or
-pnpm add typeorm-adapter-betterauth typeorm better-auth
-# or
-yarn add typeorm-adapter-betterauth typeorm better-auth
+npm install @jazim/typeorm-better-auth
 ```
 
-## Quick Start
+or with pnpm:
 
-### 1. Generate TypeORM Entities and Migrations
+```bash
+pnpm add @jazim/typeorm-better-auth
+```
 
-Run the Better-Auth CLI to generate TypeORM entity and migration files:
+or with yarn:
 
 ```bash
-npx @better-auth/cli@latest generate
+yarn add @jazim/typeorm-better-auth
 ```
 
-This will create:
-- **Entity file** (e.g., `auth-schema.ts`) with TypeORM decorators for all Better-Auth tables
-- **Migration file** (e.g., `migrations/1234567890-InitialSchema.ts`) for creating tables in production
+### Peer Dependencies
 
-### 2. Set Up TypeORM DataSource
+This package requires the following peer dependencies:
 
-Import the generated entities and create your DataSource:
+```bash
+npm install better-auth typeorm
+```
+
+## Quick Start
+
+### 1. Setup TypeORM DataSource
+
+Create a TypeORM DataSource configuration:
 
 ```typescript
-import { DataSource } from \"typeorm\";
-import { User, Session, Account, Verification } from \"./auth-schema\"; // generated file
+import { DataSource } from "typeorm";
 
-const dataSource = new DataSource({
-  type: \"postgres\", // or \"mysql\", \"sqlite\", etc.
-  host: \"localhost\",
+export const dataSource = new DataSource({
+  type: "postgres", // or "mysql" or "sqlite"
+  host: "localhost",
   port: 5432,
-  username: \"user\",
-  password: \"password\",
-  database: \"myapp\",
-  entities: [User, Session, Account, Verification],
-  migrations: [\"./migrations/*.ts\"], // Include generated migrations
-  synchronize: false, // Use migrations in production
+  username: "your_username",
+  password: "your_password",
+  database: "your_database",
+  entities: ["./entities/**/*.ts"],
+  migrations: ["./migrations/**/*.ts"],
+  synchronize: false, // Set to false in production
 });
+```
+
+### 2. Initialize the Adapter
+
+```typescript
+import { betterAuth } from "better-auth";
+import { typeormAdapter } from "@jazim/typeorm-better-auth";
+import { dataSource } from "./data-source";
 
+// Initialize the datasource
 await dataSource.initialize();
+
+export const auth = betterAuth({
+  database: typeormAdapter(dataSource, {
+    provider: "postgres",
+    entitiesPath: "./entities",
+    migrationsPath: "./migrations",
+  }),
+  // ... other Better Auth options
+});
 ```
 
-### 3. Run Migrations
+### 3. Generate Entities and Migrations
 
-For production, run migrations instead of using `synchronize: true`:
+The adapter will automatically generate TypeORM entities and migrations based on your Better Auth configuration. The generated files will be saved to the paths specified in the configuration.
 
-```bash
-# Run migrations
-npx typeorm migration:run -d ./data-source.ts
+## Configuration
 
-# Revert last migration
-npx typeorm migration:revert -d ./data-source.ts
+### TypeOrmAdapterConfig
+
+The adapter accepts a configuration object with the following options:
+
+```typescript
+interface TypeOrmAdapterConfig {
+  /**
+   * Database provider
+   * @default "postgres"
+   */
+  provider?: "mysql" | "postgres" | "sqlite";
+
+  /**
+   * Custom entity names for the adapter models
+   * @default { user: "User", account: "Account", session: "Session", verification: "Verification" }
+   */
+  entities?: {
+    user?: string;
+    account?: string;
+    session?: string;
+    verification?: string;
+  };
+
+  /**
+   * Generate TypeORM entity files
+   * @default true
+   */
+  generateEntities?: boolean;
+
+  /**
+   * Generate migration files
+   * @default true
+   */
+  generateMigrations?: boolean;
+
+  /**
+   * Path to save generated entities
+   * @default "./entities"
+   */
+  entitiesPath?: string;
+
+  /**
+   * Path to save generated migrations
+   * @default "./migrations"
+   */
+  migrationsPath?: string;
+
+  /**
+   * Enable transaction support
+   * @default false
+   */
+  transaction?: boolean;
+}
 ```
 
-### 4. Initialize Better-Auth with TypeORM Adapter
+## Usage Examples
+
+### Basic Setup with PostgreSQL
 
 ```typescript
-import { betterAuth } from \"better-auth\";
-import { typeormAdapter } from \"typeorm-adapter-betterauth\";
+import { DataSource } from "typeorm";
+import { betterAuth } from "better-auth";
+import { typeormAdapter } from "@jazim/typeorm-better-auth";
 
-const auth = betterAuth({
+const dataSource = new DataSource({
+  type: "postgres",
+  host: process.env.DB_HOST,
+  port: parseInt(process.env.DB_PORT || "5432"),
+  username: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  database: process.env.DB_NAME,
+  entities: ["./entities/**/*.ts"],
+  migrations: ["./migrations/**/*.ts"],
+});
+
+await dataSource.initialize();
+
+export const auth = betterAuth({
   database: typeormAdapter(dataSource, {
-    provider: \"postgres\", // must match your DataSource type
+    provider: "postgres",
+    entitiesPath: "./entities",
+    migrationsPath: "./migrations",
   }),
-  // ... other better-auth config
+  emailAndPassword: {
+    enabled: true,
+  },
 });
 ```
 
-## Configuration
+### Custom Entity Names
 
-### Adapter Options
+```typescript
+export const auth = betterAuth({
+  database: typeormAdapter(dataSource, {
+    provider: "postgres",
+    entities: {
+      user: "CustomUser",
+      account: "CustomAccount",
+      session: "CustomSession",
+      verification: "CustomVerification",
+    },
+    entitiesPath: "./src/entities",
+    migrationsPath: "./src/migrations",
+  }),
+});
+```
+
+### With Better Auth Model Names
+
+If you're using custom model names in Better Auth, the adapter will respect them:
 
 ```typescript
-typeormAdapter(dataSource, {
-  provider: \"postgres\", // Required: \"postgres\" | \"mysql\" | \"sqlite\" | \"mssql\" | \"oracle\" | \"mongodb\"
-  usePlural: false, // Use plural table names (users, sessions, etc.)
-  debugLogs: false, // Enable debug logs
-  transaction: false, // Enable transaction support
+export const auth = betterAuth({
+  database: typeormAdapter(dataSource, {
+    provider: "postgres",
+    entitiesPath: "./entities",
+    migrationsPath: "./migrations",
+  }),
+  user: {
+    modelName: "users", // Custom model name
+  },
+  session: {
+    modelName: "user_sessions",
+  },
 });
 ```
 
-## Complete Example
+### SQLite Configuration
 
 ```typescript
-import { betterAuth } from \"better-auth\";
-import { typeormAdapter } from \"typeorm-adapter-betterauth\";
-import { DataSource } from \"typeorm\";
-import { User, Session, Account, Verification } from \"./auth-schema\";
+import { DataSource } from "typeorm";
+import { typeormAdapter } from "@jazim/typeorm-better-auth";
 
-// 1. Create DataSource
 const dataSource = new DataSource({
-  type: \"postgres\",
-  host: process.env.DB_HOST,
-  port: parseInt(process.env.DB_PORT || \"5432\"),
-  username: process.env.DB_USER,
-  password: process.env.DB_PASSWORD,
-  database: process.env.DB_NAME,
-  entities: [User, Session, Account, Verification],
-  migrations: [\"./migrations/*.ts\"],
-  synchronize: false, // Use migrations in production
-  logging: process.env.NODE_ENV !== \"production\",
+  type: "better-sqlite3",
+  database: "./database.sqlite",
+  entities: ["./entities/**/*.ts"],
 });
 
 await dataSource.initialize();
 
-// Run migrations in production
-if (process.env.NODE_ENV === \"production\") {
-  await dataSource.runMigrations();
-}
+export const auth = betterAuth({
+  database: typeormAdapter(dataSource, {
+    provider: "sqlite",
+  }),
+});
+```
+
+### MySQL Configuration
+
+```typescript
+const dataSource = new DataSource({
+  type: "mysql",
+  host: "localhost",
+  port: 3306,
+  username: "root",
+  password: "password",
+  database: "myapp",
+  entities: ["./entities/**/*.ts"],
+});
+
+await dataSource.initialize();
 
-// 2. Create Better-Auth instance
 export const auth = betterAuth({
   database: typeormAdapter(dataSource, {
-    provider: \"postgres\",
-    transaction: true,
+    provider: "mysql",
   }),
-  emailAndPassword: {
-    enabled: true,
-  },
 });
 ```
 
+### Transaction Support
+
+Enable transaction support for better data consistency:
+
+```typescript
+export const auth = betterAuth({
+  database: typeormAdapter(dataSource, {
+    provider: "postgres",
+    transaction: true, // Enable transactions
+  }),
+});
+```
+
+### Disable Auto-Generation
+
+If you want to manage entities and migrations manually:
+
+```typescript
+export const auth = betterAuth({
+  database: typeormAdapter(dataSource, {
+    provider: "postgres",
+    generateEntities: false,
+    generateMigrations: false,
+  }),
+});
+```
+
+## Generated Files
+
+### Entity Files
+
+The adapter generates TypeORM entity files based on your Better Auth schema. Example generated entity:
+
+```typescript
+import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
+
+@Entity("user")
+export class User {
+  @PrimaryGeneratedColumn("uuid")
+  id!: string;
+
+  @Column("varchar")
+  email!: string;
+
+  @Column("varchar")
+  name!: string;
+
+  @Column("varchar", { nullable: true })
+  emailVerified?: string | null;
+
+  @Column("varchar", { nullable: true })
+  image?: string | null;
+
+  @Column("timestamp")
+  createdAt!: Date;
+
+  @Column("timestamp")
+  updatedAt!: Date;
+}
+```
+
+### Migration Files
+
+Migration files are generated with timestamps and include both `up` and `down` methods:
+
+```typescript
+import { MigrationInterface, QueryRunner, Table } from "typeorm";
+
+export class BetterAuthMigration1234567890 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.createTable(
+      new Table({
+        name: "user",
+        columns: [
+          {
+            name: "id",
+            type: "uuid",
+            isPrimary: true,
+            isGenerated: true,
+            generationStrategy: "uuid",
+          },
+          // ... more columns
+        ],
+      })
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.dropTable("user");
+  }
+}
+```
+
+## Advanced Features
+
+### Query Operators
+
+The adapter supports various query operators:
+
+- `eq` - Equal
+- `ne` - Not equal
+- `lt` - Less than
+- `lte` - Less than or equal
+- `gt` - Greater than
+- `gte` - Greater than or equal
+- `in` - In array
+- `not_in` - Not in array
+- `contains` - String contains
+- `starts_with` - String starts with
+- `ends_with` - String ends with
+
+### Error Handling
+
+The adapter provides detailed error messages wrapped in `BetterAuthError` for easier debugging:
+
+```typescript
+try {
+  await auth.api.signInEmail({
+    email: "user@example.com",
+    password: "password",
+  });
+} catch (error) {
+  console.error(error.message); // Detailed error from the adapter
+}
+```
+
+## TypeORM Integration
+
+### Running Migrations
+
+You can use TypeORM CLI to run migrations:
+
+```bash
+# Run migrations
+npx typeorm migration:run -d ./data-source.ts
+
+# Revert migrations
+npx typeorm migration:revert -d ./data-source.ts
+
+# Show migrations
+npx typeorm migration:show -d ./data-source.ts
+```
+
+### Accessing Entities
+
+You can access the generated entities in your application:
+
+```typescript
+import { User } from "./entities/auth";
+import { dataSource } from "./data-source";
+
+const userRepository = dataSource.getRepository(User);
+const users = await userRepository.find();
+```
+
+## Database Schema
+
+The adapter creates the following tables (default names):
+
+- **user** - User accounts
+- **account** - OAuth accounts linked to users
+- **session** - User sessions
+- **verification** - Email verification tokens
+
+Each table is fully compatible with Better Auth's requirements and supports all authentication features.
+
+## Best Practices
+
+1. **Production Setup**: Always set `synchronize: false` in production and use migrations
+2. **Environment Variables**: Store database credentials in environment variables
+3. **Connection Pooling**: Configure appropriate connection pool settings for your database
+4. **Migrations**: Review generated migrations before running them in production
+5. **Custom Entities**: If using custom entity names, ensure consistency across your application
+6. **Transaction Support**: Enable transactions for critical operations
+
+## Troubleshooting
+
+### Entities Not Found
+
+Make sure your TypeORM configuration includes the correct entity paths:
+
+```typescript
+entities: ["./entities/**/*.ts"], // Development
+// or
+entities: ["./dist/entities/**/*.js"], // Production
+```
+
+### Migration Errors
+
+If migrations fail:
+
+1. Check database connection
+2. Verify the provider setting matches your database type
+3. Ensure migrations directory exists
+4. Check for conflicts with existing tables
+
+### Type Errors
+
+Ensure you're using compatible versions:
+
+- `better-auth` >= 1.4.0
+- `typeorm` >= 0.3.2
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
 ## License
 
 MIT
+
+## Support
+
+For issues and questions:
+
+- [GitHub Issues](https://github.com/jazimabbas/typeorm-better-auth/issues)
+- [Better Auth Documentation](https://www.better-auth.com/docs)
+- [TypeORM Documentation](https://typeorm.io/)
+
+## Acknowledgments
+
+- [Better Auth](https://www.better-auth.com/) - Modern authentication framework
+- [TypeORM](https://typeorm.io/) - ORM for TypeScript and JavaScript
+
+---
+
+Made with ❤️ for the Better Auth community

package/dist/index.d.mts

@@ -4,7 +4,7 @@ import { DataSource } from 'typeorm';
 import { AdapterFactoryConfig } from 'better-auth/adapters';
 
 type Provider = "mysql" | "postgres" | "sqlite";
-interface TypeOrmAdapterConfig extends Pick<AdapterFactoryConfig, "debugLogs" | "usePlural" | "transaction"> {
+interface TypeOrmAdapterConfig extends Pick<AdapterFactoryConfig, "transaction" | "debugLogs"> {
     /**
      * Database provider.
      *

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { DataSource } from 'typeorm';
 import { AdapterFactoryConfig } from 'better-auth/adapters';
 
 type Provider = "mysql" | "postgres" | "sqlite";
-interface TypeOrmAdapterConfig extends Pick<AdapterFactoryConfig, "debugLogs" | "usePlural" | "transaction"> {
+interface TypeOrmAdapterConfig extends Pick<AdapterFactoryConfig, "transaction" | "debugLogs"> {
     /**
      * Database provider.
      *