@velajs/better-auth 0.1.2 → 0.2.0

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

@@ -1,7 +1,7 @@
 import type { Context } from 'hono';
-import type { BetterAuthInstance } from './better-auth.types';
+import { BetterAuthService } from './better-auth.service';
 export declare class BetterAuthCatchallController {
     private readonly auth;
-    constructor(auth: BetterAuthInstance);
+    constructor(auth: BetterAuthService);
     handle(c: Context): Promise<Response>;
 }

package/dist/better-auth.controller.js

@@ -13,10 +13,13 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 import { All, Controller, Inject, Injectable, Req } from "@velajs/vela";
-import { BETTER_AUTH } from "./better-auth.tokens.js";
+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;
     }
@@ -37,9 +40,9 @@ BetterAuthCatchallController = _ts_decorate([
     Public(true),
     Controller('/api/auth'),
     Injectable(),
-    _ts_param(0, Inject(BETTER_AUTH)),
+    _ts_param(0, Inject(BetterAuthService)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
-        typeof BetterAuthInstance === "undefined" ? Object : BetterAuthInstance
+        typeof BetterAuthService === "undefined" ? Object : BetterAuthService
     ])
 ], BetterAuthCatchallController);

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

@@ -1,16 +1,39 @@
-import { type AsyncModuleOptions, type DynamicModule } from '@velajs/vela';
+import { type DynamicModule, type Token } from '@velajs/vela';
 import type { BetterAuthInstance, BetterAuthModuleOptions } from './better-auth.types';
-type ForRootAsyncOptions = AsyncModuleOptions<{
-    auth: BetterAuthInstance;
-    basePath?: string;
-    defaultPolicy?: 'deny' | 'allow';
-}> & {
+type AsyncAuthFactory = (...deps: any[]) => BetterAuthInstance;
+interface ForRootAsyncOptions {
+    inject?: Token[];
+    imports?: DynamicModule['imports'];
+    useFactory: AsyncAuthFactory;
     isGlobal?: boolean;
     mountHandler?: boolean;
+    basePath?: string;
+    defaultPolicy?: 'deny' | 'allow';
     key?: string;
-};
+}
 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.).
+     */
     static forRoot(options: BetterAuthModuleOptions): 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), ...) })`.
+     */
     static forRootAsync(options: ForRootAsyncOptions): DynamicModule;
 }
 export {};

package/dist/better-auth.module.js

@@ -1,13 +1,19 @@
 import { APP_GUARD, stableHash } from "@velajs/vela";
 import { BetterAuthCatchallController } from "./better-auth.controller.js";
-import { BETTER_AUTH, BETTER_AUTH_OPTIONS } from "./better-auth.tokens.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';
 export class BetterAuthModule {
-    static forRoot(options) {
+    /**
+   * 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 = baseProviders(normalized, options.auth);
+        const providers = buildProviders(normalized, ()=>options.auth);
         return {
             module: BetterAuthModule,
             key: stableHash({
@@ -21,40 +27,52 @@ export class BetterAuthModule {
                 BetterAuthCatchallController
             ] : [],
             exports: [
-                BETTER_AUTH,
+                BetterAuthService,
                 BETTER_AUTH_OPTIONS,
                 AuthGuard,
                 RolesGuard
             ]
         };
     }
-    static forRootAsync(options) {
+    /**
+   * 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), ...) })`.
+   */ static forRootAsync(options) {
         const mountHandler = options.mountHandler !== false;
         const isGlobal = options.isGlobal === true;
-        const optsProvider = {
-            provide: BETTER_AUTH_OPTIONS,
-            useFactory: async (...deps)=>{
-                const value = await options.useFactory(...deps);
-                return {
-                    auth: value.auth,
-                    basePath: value.basePath ?? DEFAULT_BASE_PATH,
-                    defaultPolicy: value.defaultPolicy ?? 'deny',
+        const basePath = options.basePath ?? DEFAULT_BASE_PATH;
+        const defaultPolicy = options.defaultPolicy ?? 'deny';
+        const providers = [
+            {
+                provide: BETTER_AUTH_OPTIONS,
+                useValue: {
+                    basePath,
+                    defaultPolicy,
                     isGlobal,
                     mountHandler
-                };
+                }
             },
-            inject: options.inject ?? []
-        };
-        const authProvider = {
-            provide: BETTER_AUTH,
-            useFactory: (opts)=>opts.auth,
-            inject: [
-                BETTER_AUTH_OPTIONS
-            ]
-        };
-        const providers = [
-            optsProvider,
-            authProvider,
+            {
+                // 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.
+                provide: BETTER_AUTH_BUILDER,
+                useFactory: (...deps)=>()=>options.useFactory(...deps),
+                inject: options.inject ?? []
+            },
+            BetterAuthService,
             AuthGuard,
             RolesGuard
         ];
@@ -69,7 +87,9 @@ export class BetterAuthModule {
             key: options.key ?? stableHash({
                 inject: options.inject,
                 isGlobal,
-                mountHandler
+                mountHandler,
+                basePath,
+                defaultPolicy
             }),
             imports: options.imports ?? [],
             providers,
@@ -77,7 +97,7 @@ export class BetterAuthModule {
                 BetterAuthCatchallController
             ] : [],
             exports: [
-                BETTER_AUTH,
+                BetterAuthService,
                 BETTER_AUTH_OPTIONS,
                 AuthGuard,
                 RolesGuard
@@ -94,16 +114,17 @@ function normalize(options) {
         mountHandler: options.mountHandler ?? true
     };
 }
-function baseProviders(normalized, authInstance) {
+function buildProviders(normalized, builder) {
     const providers = [
         {
             provide: BETTER_AUTH_OPTIONS,
             useValue: normalized
         },
         {
-            provide: BETTER_AUTH,
-            useValue: authInstance
+            provide: BETTER_AUTH_BUILDER,
+            useValue: builder
         },
+        BetterAuthService,
         AuthGuard,
         RolesGuard
     ];

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

@@ -0,0 +1,42 @@
+import { InjectionToken } from '@velajs/vela';
+import type { BetterAuthInstance } from './better-auth.types';
+/**
+ * Internal token holding the auth-construction closure with its inject deps
+ * closed over. Resolves cheaply at module load (just captures references);
+ * the inner call happens lazily on first auth use (see `BetterAuthService`).
+ *
+ * Not exported from the public surface — only the service consumes it.
+ */
+export declare const BETTER_AUTH_BUILDER: InjectionToken<() => BetterAuthInstance>;
+/**
+ * The single injectable consumers reach for to interact with better-auth.
+ * Wraps the underlying `betterAuth({...})` instance with lazy construction:
+ *
+ * - `forRoot({ auth })` — the builder returns the eagerly-provided instance,
+ *   so the first `.auth` / `.api` / `.handler` access is effectively a
+ *   read-and-cache.
+ * - `forRootAsync({ inject, useFactory })` — the builder wraps the user's
+ *   factory + inject deps. First access triggers `useFactory(...deps)`. This
+ *   is what makes Cloudflare D1/KV bindings work: at module load the factory
+ *   doesn't run; on first request (when AuthGuard or the catch-all calls
+ *   `service.api` / `service.handler`), the bindings are populated and the
+ *   factory can read them safely.
+ *
+ * Used directly by AuthGuard and the catch-all controller. Consumers in
+ * application code inject the same way: `@Inject(BetterAuthService)`.
+ */
+export declare class BetterAuthService {
+    private readonly build;
+    private cached;
+    constructor(build: () => BetterAuthInstance);
+    /**
+     * The underlying better-auth instance. Constructed once on first access.
+     * Safe to call from any request-time code path (guards, controllers,
+     * services invoked from handlers).
+     */
+    get auth(): BetterAuthInstance;
+    /** Convenience accessor — equivalent to `service.auth.api`. */
+    get api(): BetterAuthInstance['api'];
+    /** Convenience accessor — equivalent to `service.auth.handler`. */
+    get handler(): BetterAuthInstance['handler'];
+}

package/dist/better-auth.service.js

@@ -0,0 +1,51 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Inject, Injectable, InjectionToken } from "@velajs/vela";
+/**
+ * Internal token holding the auth-construction closure with its inject deps
+ * closed over. Resolves cheaply at module load (just captures references);
+ * the inner call happens lazily on first auth use (see `BetterAuthService`).
+ *
+ * Not exported from the public surface — only the service consumes it.
+ */ export const BETTER_AUTH_BUILDER = new InjectionToken('vela.better-auth.Builder');
+export class BetterAuthService {
+    build;
+    cached;
+    constructor(build){
+        this.build = build;
+    }
+    /**
+   * The underlying better-auth instance. Constructed once on first access.
+   * Safe to call from any request-time code path (guards, controllers,
+   * services invoked from handlers).
+   */ get auth() {
+        if (!this.cached) this.cached = this.build();
+        return this.cached;
+    }
+    /** Convenience accessor — equivalent to `service.auth.api`. */ get api() {
+        return this.auth.api;
+    }
+    /** Convenience accessor — equivalent to `service.auth.handler`. */ get handler() {
+        return this.auth.handler;
+    }
+}
+BetterAuthService = _ts_decorate([
+    Injectable(),
+    _ts_param(0, Inject(BETTER_AUTH_BUILDER)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        Function
+    ])
+], BetterAuthService);

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

@@ -1,6 +1,5 @@
 import { InjectionToken } from '@velajs/vela';
-import type { BetterAuthInstance, BetterAuthModuleOptions } from './better-auth.types';
-export declare const BETTER_AUTH: InjectionToken<BetterAuthInstance>;
+import type { BetterAuthModuleOptions } from './better-auth.types';
 export declare const BETTER_AUTH_OPTIONS: InjectionToken<BetterAuthModuleOptions>;
 export declare const AUTH_USER_KEY: unique symbol;
 export declare const AUTH_SESSION_KEY: unique symbol;

package/dist/better-auth.tokens.js

@@ -1,5 +1,4 @@
 import { InjectionToken } from "@velajs/vela";
-export const BETTER_AUTH = new InjectionToken('vela.BetterAuth');
 export const BETTER_AUTH_OPTIONS = new InjectionToken('vela.BetterAuthOptions');
 export const AUTH_USER_KEY = Symbol.for('vela.better-auth.user');
 export const AUTH_SESSION_KEY = Symbol.for('vela.better-auth.session');

package/dist/guards/auth.guard.d.ts

@@ -1,9 +1,10 @@
 import { type CanActivate, type ExecutionContext } from '@velajs/vela';
-import type { BetterAuthInstance, BetterAuthModuleOptions } from '../better-auth.types';
+import { BetterAuthService } from '../better-auth.service';
+import type { BetterAuthModuleOptions } from '../better-auth.types';
 export declare class AuthGuard implements CanActivate {
     private readonly auth;
     private readonly opts;
     private readonly reflector;
-    constructor(auth: BetterAuthInstance, opts: BetterAuthModuleOptions);
+    constructor(auth: BetterAuthService, opts: BetterAuthModuleOptions);
     canActivate(context: ExecutionContext): Promise<boolean>;
 }

package/dist/guards/auth.guard.js

@@ -13,14 +13,20 @@ function _ts_param(paramIndex, decorator) {
     };
 }
 import { Inject, Injectable, REQUEST_CONTEXT, Reflector, UnauthorizedException } from "@velajs/vela";
-import { AUTH_SESSION_KEY, AUTH_USER_KEY, BETTER_AUTH, BETTER_AUTH_OPTIONS } from "../better-auth.tokens.js";
+import { AUTH_SESSION_KEY, AUTH_USER_KEY, BETTER_AUTH_OPTIONS } from "../better-auth.tokens.js";
+import { BetterAuthService } from "../better-auth.service.js";
 import { OptionalAuth } from "../decorators/optional-auth.decorator.js";
 import { Public } from "../decorators/public.decorator.js";
 export class AuthGuard {
     auth;
     opts;
     reflector = new Reflector();
-    constructor(auth, opts){
+    constructor(// Inject BetterAuthService rather than the raw better-auth instance.
+    // The service's lazy `.auth` getter defers construction to first use, so
+    // forRootAsync factories that depend on values only available at
+    // request time (Cloudflare D1/KV bindings, etc.) build safely on the
+    // first canActivate — not at module-load bootstrap.
+    auth, opts){
         this.auth = auth;
         this.opts = opts;
     }
@@ -47,11 +53,11 @@ export class AuthGuard {
 }
 AuthGuard = _ts_decorate([
     Injectable(),
-    _ts_param(0, Inject(BETTER_AUTH)),
+    _ts_param(0, Inject(BetterAuthService)),
     _ts_param(1, Inject(BETTER_AUTH_OPTIONS)),
     _ts_metadata("design:type", Function),
     _ts_metadata("design:paramtypes", [
-        typeof BetterAuthInstance === "undefined" ? Object : BetterAuthInstance,
+        typeof BetterAuthService === "undefined" ? Object : BetterAuthService,
         typeof BetterAuthModuleOptions === "undefined" ? Object : BetterAuthModuleOptions
     ])
 ], AuthGuard);

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { BetterAuthModule } from './better-auth.module';
+export { BetterAuthService } from './better-auth.service';
 export { BetterAuthCatchallController } from './better-auth.controller';
-export { BETTER_AUTH, BETTER_AUTH_OPTIONS, AUTH_USER_KEY, AUTH_SESSION_KEY, } from './better-auth.tokens';
+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';
 export { CurrentUser } from './decorators/current-user.decorator';

package/dist/index.js

@@ -1,8 +1,9 @@
 // Module
 export { BetterAuthModule } from "./better-auth.module.js";
+export { BetterAuthService } from "./better-auth.service.js";
 export { BetterAuthCatchallController } from "./better-auth.controller.js";
 // Tokens & symbols
-export { BETTER_AUTH, BETTER_AUTH_OPTIONS, AUTH_USER_KEY, AUTH_SESSION_KEY } from "./better-auth.tokens.js";
+export { BETTER_AUTH_OPTIONS, AUTH_USER_KEY, AUTH_SESSION_KEY } from "./better-auth.tokens.js";
 // Guards
 export { AuthGuard } from "./guards/auth.guard.js";
 export { RolesGuard } from "./guards/roles.guard.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velajs/better-auth",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "better-auth integration for the Vela framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,7 +42,7 @@
     "node": ">=20"
   },
   "peerDependencies": {
-    "@velajs/vela": ">=1.6.0",
+    "@velajs/vela": ">=1.8.1",
     "better-auth": ">=1.2.0",
     "hono": ">=4"
   },
@@ -50,7 +50,7 @@
     "@swc/cli": "^0.8.0",
     "@swc/core": "^1.15.11",
     "@velajs/testing": "^0.2.1",
-    "@velajs/vela": "^1.6.0",
+    "@velajs/vela": "^1.8.1",
     "better-auth": "^1.2.0",
     "hono": "^4",
     "typescript": "^5",