@velajs/better-auth 0.2.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.4.0 (2026-07-04)
+
+- Rebuilt on vela 1.11 `defineModule` + `lazyProvider` + `provideGlobal` (lazy auth-builder deferral preserved; public API unchanged). Requires `@velajs/vela >=1.11.0`.
+
+
 All notable changes to `@velajs/better-auth` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 

package/README.md

@@ -145,15 +145,15 @@ class AppModule {}
 
 ## Calling better-auth from services & controllers
 
-Inject the auth instance via the `BETTER_AUTH` token. The full `auth.api.*` surface is available — list sessions, revoke, impersonate, anything better-auth exposes server-side.
+Inject `BetterAuthService` — a normal `@Injectable()` exposing the underlying better-auth instance plus convenience getters for `.api` and `.handler`. The full `auth.api.*` surface is available: list sessions, revoke, impersonate, anything better-auth exposes server-side.
 
 ```ts
 import { Inject, Injectable } from '@velajs/vela';
-import { BETTER_AUTH, type BetterAuthInstance } from '@velajs/better-auth';
+import { BetterAuthService } from '@velajs/better-auth';
 
 @Injectable()
 class AdminUserService {
-  constructor(@Inject(BETTER_AUTH) private readonly auth: BetterAuthInstance) {}
+  constructor(@Inject(BetterAuthService) private readonly auth: BetterAuthService) {}
 
   listSessions(userId: string) {
     return this.auth.api.listUserSessions({ userId });
@@ -164,6 +164,8 @@ class AdminUserService {
 }
 ```
 
+Under `forRootAsync`, the underlying `betterAuth({...})` instance is constructed **lazily on first `.auth` / `.api` / `.handler` access**. That's what makes Cloudflare bindings (D1, KV, R2) work: the user factory only runs after request-time middleware has populated env. No proxies, no lifecycle hooks — just a service with a cached field.
+
 ## Decorators
 
 | Decorator           | Purpose                                                                  |
@@ -210,13 +212,13 @@ Set `mountHandler: false` and mount the catch-all yourself if you need a base pa
 
 ```ts
 import { Controller, All, Req, Inject, Injectable } from '@velajs/vela';
-import { BETTER_AUTH, Public } from '@velajs/better-auth';
+import { BetterAuthService, Public } from '@velajs/better-auth';
 
 @Public(true)
 @Controller('/auth')
 @Injectable()
 class CustomCatchallController {
-  constructor(@Inject(BETTER_AUTH) private auth: BetterAuthInstance) {}
+  constructor(@Inject(BetterAuthService) private auth: BetterAuthService) {}
   @All('/*') handle(@Req() c: Context) { return this.auth.handler(c.req.raw); }
 }
 ```

package/dist/better-auth.controller.d.ts

@@ -1,7 +1,21 @@
-import type { Context } from 'hono';
-import { BetterAuthService } from './better-auth.service';
-export declare class BetterAuthCatchallController {
-    private readonly auth;
-    constructor(auth: BetterAuthService);
-    handle(c: Context): Promise<Response>;
-}
+import { type Type } from '@velajs/vela';
+/**
+ * Build a catch-all controller that mounts better-auth's handler at `basePath`
+ * (default `/api/auth`). This is a factory because vela reads a controller's
+ * route off the class at decoration time, so a custom base path needs its own
+ * decorated class — the path can't be parametrized on a single shared class.
+ *
+ * Two base paths to keep consistent:
+ * - this `basePath` is RELATIVE to vela's `globalPrefix` (always prepended);
+ * - better-auth routes against its OWN absolute `basePath` (the one you pass to
+ *   `betterAuth({ basePath })`), which must equal `globalPrefix + basePath`.
+ *
+ * Both default to `/api/auth`, so the no-prefix / no-config case just works.
+ */
+export declare function createBetterAuthCatchallController(basePath?: string): Type;
+/**
+ * Default-path (`/api/auth`) catch-all controller. Retained for back-compat;
+ * `BetterAuthModule` now mounts {@link createBetterAuthCatchallController} with
+ * the configured `basePath`. Prefer the factory for a custom base path.
+ */
+export declare const BetterAuthCatchallController: Type;

package/dist/better-auth.controller.js

@@ -15,34 +15,54 @@ function _ts_param(paramIndex, decorator) {
 import { All, Controller, Inject, Injectable, Req } from "@velajs/vela";
 import { BetterAuthService } from "./better-auth.service.js";
 import { Public } from "./decorators/public.decorator.js";
-export class BetterAuthCatchallController {
-    auth;
-    // Inject the service — its `.handler` getter triggers lazy construction
-    // of the underlying betterAuth() instance on first access, AFTER any
-    // runtime adapter middleware (Cloudflare env capture) has run.
-    constructor(auth){
-        this.auth = auth;
-    }
-    async handle(c) {
-        return this.auth.handler(c.req.raw);
-    }
+/**
+ * Build a catch-all controller that mounts better-auth's handler at `basePath`
+ * (default `/api/auth`). This is a factory because vela reads a controller's
+ * route off the class at decoration time, so a custom base path needs its own
+ * decorated class — the path can't be parametrized on a single shared class.
+ *
+ * Two base paths to keep consistent:
+ * - this `basePath` is RELATIVE to vela's `globalPrefix` (always prepended);
+ * - better-auth routes against its OWN absolute `basePath` (the one you pass to
+ *   `betterAuth({ basePath })`), which must equal `globalPrefix + basePath`.
+ *
+ * Both default to `/api/auth`, so the no-prefix / no-config case just works.
+ */ export function createBetterAuthCatchallController(basePath = '/api/auth') {
+    let BetterAuthCatchallController = class BetterAuthCatchallController {
+        auth;
+        // Inject the service — its `.handler` getter triggers lazy construction
+        // of the underlying betterAuth() instance on first access, AFTER any
+        // runtime adapter middleware (Cloudflare env capture) has run.
+        constructor(auth){
+            this.auth = auth;
+        }
+        async handle(c) {
+            return this.auth.handler(c.req.raw);
+        }
+    };
+    _ts_decorate([
+        All('/*'),
+        _ts_param(0, Req()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Context === "undefined" ? Object : Context
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], BetterAuthCatchallController.prototype, "handle", null);
+    BetterAuthCatchallController = _ts_decorate([
+        Public(true),
+        Controller(basePath),
+        Injectable(),
+        _ts_param(0, Inject(BetterAuthService)),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof BetterAuthService === "undefined" ? Object : BetterAuthService
+        ])
+    ], BetterAuthCatchallController);
+    return BetterAuthCatchallController;
 }
-_ts_decorate([
-    All('/*'),
-    _ts_param(0, Req()),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof Context === "undefined" ? Object : Context
-    ]),
-    _ts_metadata("design:returntype", Promise)
-], BetterAuthCatchallController.prototype, "handle", null);
-BetterAuthCatchallController = _ts_decorate([
-    Public(true),
-    Controller('/api/auth'),
-    Injectable(),
-    _ts_param(0, Inject(BetterAuthService)),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof BetterAuthService === "undefined" ? Object : BetterAuthService
-    ])
-], BetterAuthCatchallController);
+/**
+ * Default-path (`/api/auth`) catch-all controller. Retained for back-compat;
+ * `BetterAuthModule` now mounts {@link createBetterAuthCatchallController} with
+ * the configured `basePath`. Prefer the factory for a custom base path.
+ */ export const BetterAuthCatchallController = createBetterAuthCatchallController();

package/dist/better-auth.module.d.ts

@@ -3,22 +3,17 @@ import type { BetterAuthInstance, BetterAuthModuleOptions } from './better-auth.
 /**
  * Options for {@link BetterAuthModule.forRootAsync}.
  *
- * The `Inject` type parameter captures the literal `inject` tuple at the
- * call site (via `const` inference on the consuming generic) so
- * `useFactory` parameters are typed from the inject array, position-by-position.
- * No `as const`, no `(...deps: any[])` workaround:
+ * The `Inject` type parameter captures the literal `inject` tuple at the call
+ * site (via `const` inference) so `useFactory` parameters are typed from the
+ * inject array, position-by-position — no `as const`, no `(...deps: any[])`:
  *
  * ```ts
  * BetterAuthModule.forRootAsync({
  *   inject: [D1Service, ConfigService],   // captured as readonly tuple
- *   useFactory: (d1, config) =>             // d1: D1Service, config: ConfigService
+ *   useFactory: (d1, config) =>            // d1: D1Service, config: ConfigService
  *     betterAuth({ database: drizzleAdapter(drizzle(d1.database), ...) }),
  * });
  * ```
- *
- * When `inject` isn't a literal tuple (or is omitted), `Inject` falls back
- * to `readonly Token<unknown>[]` and `useFactory` accepts variadic
- * `unknown[]` — the historical loose-typing behavior.
  */
 interface ForRootAsyncOptions<Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]> {
     inject?: Inject;
@@ -32,26 +27,25 @@ interface ForRootAsyncOptions<Inject extends readonly Token<unknown>[] = readonl
 }
 export declare class BetterAuthModule {
     /**
-     * Synchronous registration. The auth instance is constructed by the
-     * consumer at module-load time and passed in directly. Use this when the
-     * inputs to `betterAuth({...})` are available at startup (Node apps with
-     * a static DB connection, in-memory adapters, etc.).
+     * Synchronous registration. The auth instance is constructed by the consumer
+     * at module-load time and passed in directly. Use this when the inputs to
+     * `betterAuth({...})` are available at startup (Node apps with a static DB
+     * connection, in-memory adapters, etc.).
      */
-    static forRoot(options: BetterAuthModuleOptions): DynamicModule;
+    static forRoot(options: BetterAuthModuleOptions & {
+        isGlobal?: boolean;
+        key?: string;
+    }): DynamicModule;
     /**
-     * Deferred / DI-driven registration. The user factory runs **lazily**, on
-     * the first time anything reads `BetterAuthService.auth` (or `.api` /
-     * `.handler`). In normal request handling, that's `AuthGuard.canActivate`
-     * or the catch-all controller's `.handle`. At module load, the factory
-     * does NOT run — it's only captured as a closure inside the builder
-     * thunk. This is what makes Cloudflare bindings (D1, KV, R2) work: the
-     * binding isn't ready at boot, but it IS by the time a request flows
-     * through and the guard / catch-all reads the service.
-     *
-     * Inject deps are resolved at module load (cheap; e.g. D1Service is a
-     * thin BindingRef wrapper). Their *values* are read at first auth use,
-     * inside your factory body — `(d1: D1Service) => betterAuth({ database:
-     * drizzleAdapter(drizzle(d1.database), ...) })`.
+     * Deferred / DI-driven registration. The user factory runs **lazily**, on the
+     * first time anything reads `BetterAuthService.auth` (or `.api` / `.handler`).
+     * In normal request handling that's `AuthGuard.canActivate` or the catch-all
+     * controller's `.handle`. At module load the factory does NOT run — it's only
+     * captured behind {@link lazyProvider}'s memoized thunk. This is what makes
+     * Cloudflare bindings (D1, KV, R2) work: the binding isn't ready at boot, but
+     * it IS by the time a request flows through and the guard / catch-all reads
+     * the service. Inject deps resolve at module load (cheap BindingRef wrappers);
+     * their *values* are read at first auth use, inside your factory body.
      */
     static forRootAsync<const Inject extends readonly Token<unknown>[] = readonly Token<unknown>[]>(options: ForRootAsyncOptions<Inject>): DynamicModule;
 }

package/dist/better-auth.module.js

@@ -1,144 +1,138 @@
-import { APP_GUARD, stableHash } from "@velajs/vela";
-import { BetterAuthCatchallController } from "./better-auth.controller.js";
+import { defineModule, lazyProvider, provideGlobal, stableHash } from "@velajs/vela";
+import { createBetterAuthCatchallController } from "./better-auth.controller.js";
 import { BetterAuthService, BETTER_AUTH_BUILDER } from "./better-auth.service.js";
 import { BETTER_AUTH_OPTIONS } from "./better-auth.tokens.js";
 import { AuthGuard } from "./guards/auth.guard.js";
 import { RolesGuard } from "./guards/roles.guard.js";
 const DEFAULT_BASE_PATH = '/api/auth';
+function normalize(options) {
+    return {
+        basePath: options.basePath ?? DEFAULT_BASE_PATH,
+        isGlobal: options.isGlobal ?? false,
+        defaultPolicy: options.defaultPolicy ?? 'deny',
+        mountHandler: options.mountHandler ?? true
+    };
+}
+/** Providers, controllers, and exports shared by both entry points. */ function commonContributions(n) {
+    return {
+        providers: [
+            BetterAuthService,
+            AuthGuard,
+            RolesGuard
+        ],
+        controllers: n.mountHandler ? [
+            createBetterAuthCatchallController(n.basePath)
+        ] : [],
+        exports: [
+            BetterAuthService,
+            BETTER_AUTH_OPTIONS,
+            AuthGuard,
+            RolesGuard
+        ]
+    };
+}
+/**
+ * The blessed engine generates `forRoot`. `setup` runs once per instance at
+ * call time: it re-provides {@link BETTER_AUTH_OPTIONS} with defaults applied,
+ * derives the auth builder from those options, mounts the catch-all controller,
+ * and — via the `global:` slot — registers the app-wide guard when `isGlobal`.
+ *
+ * `isGlobal` here means "apply AuthGuard app-wide", NOT "make this a global
+ * module", so the default `isGlobal → global: true` extras transform is
+ * replaced with identity; the flag reaches `setup` through the options bag.
+ */ const authModuleHost = defineModule({
+    name: 'BetterAuth',
+    optionsToken: BETTER_AUTH_OPTIONS,
+    transform: (definition)=>definition,
+    // The auth instance is a stateful value — key off the structural subset only.
+    key: (options)=>stableHash(normalize(options)),
+    setup: ({ OPTIONS, options })=>{
+        const n = normalize(options);
+        const common = commonContributions(n);
+        const auth = options.auth;
+        return {
+            providers: [
+                // Override the auto-provided raw bag with the normalized shape so
+                // BETTER_AUTH_OPTIONS consumers always see defaults + the auth instance.
+                {
+                    provide: OPTIONS,
+                    useValue: {
+                        ...n,
+                        auth
+                    }
+                },
+                // Eager auth: the builder hands back the instance the caller passed in.
+                lazyProvider({
+                    provide: BETTER_AUTH_BUILDER,
+                    inject: [
+                        OPTIONS
+                    ],
+                    useFactory: (o)=>o.auth
+                }),
+                ...common.providers
+            ],
+            controllers: common.controllers,
+            exports: common.exports,
+            global: n.isGlobal ? {
+                guards: [
+                    AuthGuard
+                ]
+            } : undefined
+        };
+    }
+});
 export class BetterAuthModule {
     /**
-   * Synchronous registration. The auth instance is constructed by the
-   * consumer at module-load time and passed in directly. Use this when the
-   * inputs to `betterAuth({...})` are available at startup (Node apps with
-   * a static DB connection, in-memory adapters, etc.).
+   * Synchronous registration. The auth instance is constructed by the consumer
+   * at module-load time and passed in directly. Use this when the inputs to
+   * `betterAuth({...})` are available at startup (Node apps with a static DB
+   * connection, in-memory adapters, etc.).
    */ static forRoot(options) {
-        const normalized = normalize(options);
-        const providers = buildProviders(normalized, ()=>options.auth);
+        // Delegate to the generated static, then rebrand the module identity so the
+        // public `BetterAuthModule` class is the one registered (consistent with
+        // `forRootAsync` and better diagnostics).
         return {
-            module: BetterAuthModule,
-            key: stableHash({
-                basePath: normalized.basePath,
-                defaultPolicy: normalized.defaultPolicy,
-                isGlobal: !!options.isGlobal,
-                mountHandler: !!normalized.mountHandler
-            }),
-            providers,
-            controllers: normalized.mountHandler ? [
-                BetterAuthCatchallController
-            ] : [],
-            exports: [
-                BetterAuthService,
-                BETTER_AUTH_OPTIONS,
-                AuthGuard,
-                RolesGuard
-            ]
+            ...authModuleHost.ConfigurableModuleClass.forRoot(options),
+            module: BetterAuthModule
         };
     }
     /**
-   * Deferred / DI-driven registration. The user factory runs **lazily**, on
-   * the first time anything reads `BetterAuthService.auth` (or `.api` /
-   * `.handler`). In normal request handling, that's `AuthGuard.canActivate`
-   * or the catch-all controller's `.handle`. At module load, the factory
-   * does NOT run — it's only captured as a closure inside the builder
-   * thunk. This is what makes Cloudflare bindings (D1, KV, R2) work: the
-   * binding isn't ready at boot, but it IS by the time a request flows
-   * through and the guard / catch-all reads the service.
-   *
-   * Inject deps are resolved at module load (cheap; e.g. D1Service is a
-   * thin BindingRef wrapper). Their *values* are read at first auth use,
-   * inside your factory body — `(d1: D1Service) => betterAuth({ database:
-   * drizzleAdapter(drizzle(d1.database), ...) })`.
+   * Deferred / DI-driven registration. The user factory runs **lazily**, on the
+   * first time anything reads `BetterAuthService.auth` (or `.api` / `.handler`).
+   * In normal request handling that's `AuthGuard.canActivate` or the catch-all
+   * controller's `.handle`. At module load the factory does NOT run — it's only
+   * captured behind {@link lazyProvider}'s memoized thunk. This is what makes
+   * Cloudflare bindings (D1, KV, R2) work: the binding isn't ready at boot, but
+   * it IS by the time a request flows through and the guard / catch-all reads
+   * the service. Inject deps resolve at module load (cheap BindingRef wrappers);
+   * their *values* are read at first auth use, inside your factory body.
    */ static forRootAsync(options) {
-        const mountHandler = options.mountHandler !== false;
-        const isGlobal = options.isGlobal === true;
-        const basePath = options.basePath ?? DEFAULT_BASE_PATH;
-        const defaultPolicy = options.defaultPolicy ?? 'deny';
-        const providers = [
-            {
-                provide: BETTER_AUTH_OPTIONS,
-                useValue: {
-                    basePath,
-                    defaultPolicy,
-                    isGlobal,
-                    mountHandler
-                }
-            },
-            {
-                // The builder is a zero-arg closure capturing the DI'd deps. It is
-                // invoked lazily by BetterAuthService.auth on first access; vela
-                // can resolve this provider at module load without running the user
-                // factory — the factory body lives behind the closure.
-                //
-                // The inner factory is typed `unknown[]` (vela's runtime contract:
-                // deps are resolved by token order). The outer user-facing
-                // `options.useFactory` is statically typed via `InferTokens<Inject>`.
-                // We narrow at the boundary with a single cast — runtime order
-                // matches the declared `inject` order by construction.
-                provide: BETTER_AUTH_BUILDER,
-                useFactory: (...deps)=>()=>options.useFactory(...deps),
-                inject: options.inject ?? []
-            },
-            BetterAuthService,
-            AuthGuard,
-            RolesGuard
-        ];
-        if (isGlobal) {
-            providers.push({
-                provide: APP_GUARD,
-                useExisting: AuthGuard
-            });
-        }
+        const n = normalize(options);
+        const common = commonContributions(n);
         return {
             module: BetterAuthModule,
             key: options.key ?? stableHash({
-                inject: options.inject,
-                isGlobal,
-                mountHandler,
-                basePath,
-                defaultPolicy
+                ...n,
+                inject: options.inject
             }),
             imports: options.imports ?? [],
-            providers,
-            controllers: mountHandler ? [
-                BetterAuthCatchallController
-            ] : [],
-            exports: [
-                BetterAuthService,
-                BETTER_AUTH_OPTIONS,
-                AuthGuard,
-                RolesGuard
-            ]
+            providers: [
+                {
+                    provide: BETTER_AUTH_OPTIONS,
+                    useValue: n
+                },
+                // The deferred auth builder: `lazyProvider` wraps the user factory in a
+                // memoized thunk, replacing the hand-rolled `(...deps) => () => f(...deps)`.
+                lazyProvider({
+                    provide: BETTER_AUTH_BUILDER,
+                    inject: options.inject,
+                    useFactory: options.useFactory
+                }),
+                ...common.providers,
+                ...n.isGlobal ? provideGlobal('guard', AuthGuard) : []
+            ],
+            controllers: common.controllers,
+            exports: common.exports
         };
     }
 }
-function normalize(options) {
-    return {
-        auth: options.auth,
-        basePath: options.basePath ?? DEFAULT_BASE_PATH,
-        isGlobal: options.isGlobal ?? false,
-        defaultPolicy: options.defaultPolicy ?? 'deny',
-        mountHandler: options.mountHandler ?? true
-    };
-}
-function buildProviders(normalized, builder) {
-    const providers = [
-        {
-            provide: BETTER_AUTH_OPTIONS,
-            useValue: normalized
-        },
-        {
-            provide: BETTER_AUTH_BUILDER,
-            useValue: builder
-        },
-        BetterAuthService,
-        AuthGuard,
-        RolesGuard
-    ];
-    if (normalized.isGlobal) {
-        providers.push({
-            provide: APP_GUARD,
-            useExisting: AuthGuard
-        });
-    }
-    return providers;
-}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { BetterAuthModule } from './better-auth.module';
 export { BetterAuthService } from './better-auth.service';
-export { BetterAuthCatchallController } from './better-auth.controller';
+export { BetterAuthCatchallController, createBetterAuthCatchallController, } from './better-auth.controller';
 export { BETTER_AUTH_OPTIONS, AUTH_USER_KEY, AUTH_SESSION_KEY, } from './better-auth.tokens';
 export { AuthGuard } from './guards/auth.guard';
 export { RolesGuard } from './guards/roles.guard';

package/dist/index.js

@@ -1,7 +1,7 @@
 // Module
 export { BetterAuthModule } from "./better-auth.module.js";
 export { BetterAuthService } from "./better-auth.service.js";
-export { BetterAuthCatchallController } from "./better-auth.controller.js";
+export { BetterAuthCatchallController, createBetterAuthCatchallController } from "./better-auth.controller.js";
 // Tokens & symbols
 export { BETTER_AUTH_OPTIONS, AUTH_USER_KEY, AUTH_SESSION_KEY } from "./better-auth.tokens.js";
 // Guards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/better-auth",
-  "version": "0.2.2",
+  "version": "0.5.0",
   "description": "better-auth integration for the Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,20 +42,20 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@velajs/vela": ">=1.8.2",
+    "@velajs/vela": ">=1.11.0",
     "better-auth": ">=1.2.0",
     "hono": ">=4"
   },
   "devDependencies": {
-    "@swc/cli": "^0.8.0",
-    "@swc/core": "^1.15.11",
-    "@velajs/testing": "^0.2.1",
-    "@velajs/vela": "^1.8.2",
-    "better-auth": "^1.2.0",
-    "hono": "^4",
-    "typescript": "^5",
+    "@swc/cli": "^0.8.1",
+    "@swc/core": "^1.15.41",
+    "@velajs/testing": "^0.4.0",
+    "@velajs/vela": "^1.12.0",
+    "better-auth": "^1.6.20",
+    "hono": "^4.12.26",
+    "typescript": "^6.0.3",
     "unplugin-swc": "^1.5.9",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.9"
   },
   "scripts": {
     "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",