@stratal/framework

Higher-level framework modules for Stratal: authentication (Better Auth), database ORM (ZenStack), RBAC (Casbin), authorization guards, and test data factories. Full documentation at stratal.dev/framework.

Authentication (AuthModule)

Docs: Auth

@Module({
  imports: [
    AuthModule.forRootAsync({
      inject: [authConfig.KEY],
      useFactory: (config) => ({
        secret: config.secret,
        baseURL: config.baseURL,
        // ...Better Auth options
      }),
    }),
  ],
})
export class AppModule {}

AuthContext is request-scoped and available via @inject(DI_TOKENS.AuthContext). Key methods: isAuthenticated(), getUserId(), requireUserId(), getAuthContext(). AuthModule auto-registers session verification middleware.

Database (DatabaseModule)

Docs: Database · Database Events

Each connection brings its own ZenStack schema. Users write per-connection .zmodel files, run zenstack generate independently, and pass each connection's schema in the config.

import { PostgresDialect } from '@zenstackhq/orm/dialects/postgres';
import { Pool } from 'pg';
import { schema } from '../db/main/schema';

DatabaseModule.forRootAsync({
  inject: [DI_TOKENS.CloudflareEnv],
  useFactory: (env: StratalEnv) => ({
    default: 'main',
    connections: [
      {
        name: 'main',
        schema,
        dialect: () => new PostgresDialect({
          pool: new Pool({ connectionString: env.DB.connectionString, max: 1 }),
        }),
      },
    ],
  }),
})

Type augmentation:

declare module '@stratal/framework/database' {
  interface StratalDatabase {
    schemas: {
      main: MainSchemaType;
      analytics: AnalyticsSchemaType;
    };
    defaultConnection: 'main';
  }
}

Inject with @inject(DI_TOKENS.Database) (default connection) or @InjectDB('name') (named). Plugins: EventEmitterPlugin, SchemaSwitcherPlugin, ErrorHandlerPlugin.

Database events follow the pattern {phase}.{Model}.{operation} — e.g., after.User.create. Augment CustomEventRegistry with DatabaseEvents<ConnectionName> for type safety.

Multi-Connection Per-Connection Schemas

Each connection has its own .zmodel file and its own zenstack generate output. For shared models, use ZenStack's native import/extends between schema files.

Per-connection schema setup:

db/
  main/
    schema.zmodel      # Main connection models
    schema.ts          # Generated by zenstack generate
  analytics/
    schema.zmodel      # Analytics connection models
    schema.ts          # Generated by zenstack generate

Config with per-connection schemas:

import { schema as mainSchema } from '../db/main/schema';
import { schema as analyticsSchema } from '../db/analytics/schema';

DatabaseModule.forRootAsync({
  inject: [DI_TOKENS.CloudflareEnv],
  useFactory: (env: StratalEnv) => ({
    default: 'main',
    connections: [
      { name: 'main', schema: mainSchema, dialect: () => ... },
      { name: 'analytics', schema: analyticsSchema, dialect: () => ... },
    ],
  }),
})

Migrations — use standard ZenStack commands per connection:

zenstack db push --schema db/main/schema.zmodel
zenstack db push --schema db/analytics/schema.zmodel

RBAC (RbacModule)

Docs: RBAC

RbacModule.forRoot({
  model: casbinModel,
  defaultPolicies: [['admin', 'users:*', '.*']],
  roleHierarchy: [['super_admin', 'admin']],
})

CasbinService is request-scoped. Key methods: hasPermission(), currentUserHasPermission(), hasAnyPermission(), currentUserHasAnyPermission(), addRoleForUser(), getRolesForUser(), getCurrentUserRoles(). Requires a CasbinRule model in your ZenStack schema.

AuthGuard

Docs: AuthGuard

// Auth only — checks isAuthenticated()
@UseGuards(AuthGuard())

// Auth + permissions — checks isAuthenticated() + CasbinService
@UseGuards(AuthGuard({ scopes: ['users:read'] }))

Throws UserNotAuthenticatedError (401) or InsufficientPermissionsError (403). Apply at class or method level.

Test Factories

Docs: Factories

export class UserFactory extends Factory<User, UserCreateInput> {
  protected model = 'user';
  protected definition() {
    return {
      email: this.faker.internet.email(),
      name: this.faker.person.fullName(),
    };
  }
  admin() {
    return this.state((attrs) => ({ ...attrs, role: 'admin' }));
  }
}

// Usage
const user = await new UserFactory().create(db);
const admins = await new UserFactory().admin().count(5).createManyAndReturn(db);

Methods: make() (build without saving), create() (persist), makeMany(), createMany(), createManyAndReturn(). Use state() for variants and count() for batch creation.

Sub-path Imports

Path	Key Exports
@stratal/framework/auth	AuthModule, AuthService, AuthContext
@stratal/framework/database	DatabaseModule, DatabaseService, @InjectDB, databaseI18n
@stratal/framework/rbac	RbacModule, CasbinService
@stratal/framework/guards	AuthGuard
@stratal/framework/factory	Factory, Sequence
@stratal/framework/context	RequestContext